From b6b900920c151f92bc695824ac846d11b137ec39 Mon Sep 17 00:00:00 2001 From: Ole Loots Date: Thu, 10 Jan 2013 01:27:36 +0100 Subject: Added some inline documentation --- atari/gemtk/gemtk.h | 127 +++++++++++++++++++++++++++++++---------- atari/gemtk/guiwin.c | 158 ++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 233 insertions(+), 52 deletions(-) diff --git a/atari/gemtk/gemtk.h b/atari/gemtk/gemtk.h index 01588dc63..bc84ed073 100644 --- a/atari/gemtk/gemtk.h +++ b/atari/gemtk/gemtk.h @@ -132,51 +132,118 @@ typedef struct gui_window_s GUIWIN; typedef short (*guiwin_event_handler_f)(GUIWIN *gw, EVMULT_OUT *ev_out, short msg[8]); struct guiwin_scroll_info_s { + + /** Definition of a content unit (horizontal) measured in pixel */ int x_unit_px; + + /** Definition of content unit (vertical) measured in pixel */ int y_unit_px; + + /** Current scroll position (in content units) */ int x_pos; + + /** Current scroll position (in content units) */ int y_pos; + + /** Size of content (horizontal) measured in content units */ int x_units; + + /** Size of content (vertical) measured in content units */ int y_units; }; +/** Well known areas inside the window */ enum guwin_area_e { GUIWIN_AREA_WORK = 0, GUIWIN_AREA_TOOLBAR, GUIWIN_AREA_CONTENT }; -short guiwin_init(void); -void guiwin_exit(void); -GUIWIN * guiwin_add(short handle, uint32_t flags, - guiwin_event_handler_f handler); -GUIWIN *guiwin_find(short handle); -short guiwin_remove(GUIWIN *win); -GUIWIN *guiwin_validate_ptr(GUIWIN *win); -short guiwin_dispatch_event(EVMULT_IN *ev_in, EVMULT_OUT *ev_out, - short msg[8]); -void guiwin_get_grect(GUIWIN *win, enum guwin_area_e mode, GRECT *dest); -short guiwin_get_handle(GUIWIN *win); -uint32_t guiwin_get_state(GUIWIN *win); -void guiwin_set_toolbar(GUIWIN *win, OBJECT *toolbar, short idx, - uint32_t flags); -void guiwin_set_event_handler(GUIWIN *win,guiwin_event_handler_f cb); -void guiwin_set_user_data(GUIWIN *win, void *data); -void *guiwin_get_user_data(GUIWIN *win); -struct guiwin_scroll_info_s * guiwin_get_scroll_info(GUIWIN *win); -void guiwin_set_scroll_grid(GUIWIN * win, short x, short y); -void guiwin_set_content_units(GUIWIN * win, short x, short y); -void guiwin_set_form(GUIWIN *win, OBJECT *tree, short index); -bool guiwin_update_slider(GUIWIN *win, short mode); -void guiwin_scroll(GUIWIN *gw, short orientation, int units, bool refresh); -void guiwin_send_msg(GUIWIN *win, short msgtype, short a, short b, short c, +/* -------------------------------------------------------------------------- */ +/* GUIWIN functions (document in guiwin.c) */ +/* -------------------------------------------------------------------------- */ + +short +guiwin_init(void); + +void +guiwin_exit(void); + +GUIWIN * +guiwin_add(short handle, uint32_t flags, guiwin_event_handler_f handler); + +GUIWIN * +guiwin_find(short handle); + +short +guiwin_remove(GUIWIN *win); + +GUIWIN * +guiwin_validate_ptr(GUIWIN *win); + +short +guiwin_dispatch_event(EVMULT_IN *ev_in, EVMULT_OUT *ev_out, short msg[8]); + +void +guiwin_get_grect(GUIWIN *win, enum guwin_area_e mode, GRECT *dest); + +short +guiwin_get_handle(GUIWIN *win); + +uint32_t +guiwin_get_state(GUIWIN *win); + +void +guiwin_set_toolbar(GUIWIN *win, OBJECT *toolbar, short idx, uint32_t flags); + +void +guiwin_set_event_handler(GUIWIN *win,guiwin_event_handler_f cb); + +void +guiwin_set_user_data(GUIWIN *win, void *data); + +void * +guiwin_get_user_data(GUIWIN *win); + +struct guiwin_scroll_info_s * +guiwin_get_scroll_info(GUIWIN *win); + +void +guiwin_set_scroll_grid(GUIWIN * win, short x, short y); + +void +guiwin_set_content_units(GUIWIN * win, short x, short y); + +void +guiwin_set_form(GUIWIN *win, OBJECT *tree, short index); + +bool +guiwin_update_slider(GUIWIN *win, short mode); + +void +guiwin_scroll(GUIWIN *gw, short orientation, int units, bool refresh); + +void +guiwin_send_msg(GUIWIN *win, short msgtype, short a, short b, short c, short d); -void guiwin_send_redraw(GUIWIN *win, GRECT *area); -VdiHdl guiwin_get_vdi_handle(GUIWIN *win); -bool guiwin_has_intersection(GUIWIN *win, GRECT *work); -void guiwin_toolbar_redraw(GUIWIN *win, GRECT *clip); -void guiwin_form_redraw(GUIWIN *gw, GRECT *clip); -void guiwin_clear(GUIWIN *win); + +void +guiwin_send_redraw(GUIWIN *win, GRECT *area); + +VdiHdl +guiwin_get_vdi_handle(GUIWIN *win); + +bool +guiwin_has_intersection(GUIWIN *win, GRECT *work); + +void +guiwin_toolbar_redraw(GUIWIN *win, GRECT *clip); + +void +guiwin_form_redraw(GUIWIN *gw, GRECT *clip); + +void +guiwin_clear(GUIWIN *win); /* -------------------------------------------------------------------------- */ /* AES SCROLLER MODULE */ diff --git a/atari/gemtk/guiwin.c b/atari/gemtk/guiwin.c index 666200bfc..8d75c332f 100644 --- a/atari/gemtk/guiwin.c +++ b/atari/gemtk/guiwin.c @@ -37,6 +37,7 @@ struct gui_window_s { OBJECT *toolbar; short toolbar_edit_obj; short toolbar_idx; + GRECT toolbar_dim; OBJECT *form; short form_edit_obj; short form_focus_obj; @@ -281,6 +282,9 @@ static short preproc_wm(GUIWIN * gw, EVMULT_OUT *ev_out, short msg[8]) return(retval); } +/** +* Preprocess mouse events +*/ static short preproc_mu_button(GUIWIN * gw, EVMULT_OUT *ev_out, short msg[8]) { short retval = 0; @@ -421,6 +425,9 @@ static short preproc_mu_button(GUIWIN * gw, EVMULT_OUT *ev_out, short msg[8]) return(retval); } +/** +* Preprocess keyboard events (for forms/toolbars) +*/ static short preproc_mu_keybd(GUIWIN * gw, EVMULT_OUT *ev_out, short msg[8]) { @@ -457,6 +464,10 @@ static short preproc_mu_keybd(GUIWIN * gw, EVMULT_OUT *ev_out, short msg[8]) } } +/** +* Event Dispatcher function. The guiwin API doesn't own an event loop, +* so you have to inform it for every event that you want it to handle. +*/ short guiwin_dispatch_event(EVMULT_IN *ev_in, EVMULT_OUT *ev_out, short msg[8]) { GUIWIN *dest; @@ -539,6 +550,9 @@ short guiwin_dispatch_event(EVMULT_IN *ev_in, EVMULT_OUT *ev_out, short msg[8]) return(retval); } +/** +* Initialises the guiwin API +*/ short guiwin_init(void) { if(v_vdi_h == -1) { @@ -555,6 +569,14 @@ void guiwin_exit(void) v_clsvwk(v_vdi_h); } +/** +* Adds and AES handle to the guiwin list and creates and GUIWIN management +* structure. +* +* \param handle The AES handle +* \param flags Creation flags, configures how the AES window is handled +* \param cb event handler function for that window +*/ GUIWIN * guiwin_add(short handle, uint32_t flags, guiwin_event_handler_f cb) { @@ -584,6 +606,9 @@ GUIWIN * guiwin_add(short handle, uint32_t flags, guiwin_event_handler_f cb) return(win); } +/** +* Returns an GUIWIN* for AES handle, when that AES window is managed by guiwin +*/ GUIWIN *guiwin_find(short handle) { GUIWIN *g; @@ -597,6 +622,10 @@ GUIWIN *guiwin_find(short handle) return(NULL); } + +/** +* Check's if the pointer is managed by the guiwin API. +*/ GUIWIN *guiwin_validate_ptr(GUIWIN *win) { GUIWIN *g; @@ -610,6 +639,10 @@ GUIWIN *guiwin_validate_ptr(GUIWIN *win) return(NULL); } +/** +* Remove an GUIWIN from the list of managed windows. +* Call this when the AES window is closed or deleted. +*/ short guiwin_remove(GUIWIN *win) { win = guiwin_validate_ptr(win); @@ -630,6 +663,11 @@ short guiwin_remove(GUIWIN *win) return(0); } +/** Calculate & get a well known area within the GUIWIN. +* \param win The GUIWIN ptr. +* \param mode Specifies the area to retrieve. +* \param dest The calculated rectangle. +*/ void guiwin_get_grect(GUIWIN *win, enum guwin_area_e mode, GRECT *dest) { @@ -642,32 +680,43 @@ void guiwin_get_grect(GUIWIN *win, enum guwin_area_e mode, GRECT *dest) if (win->flags & GW_FLAG_HAS_VTOOLBAR) { dest->g_x += tb_area.g_w; dest->g_w -= tb_area.g_w; - } else { - dest->g_y += tb_area.g_h; + } + else { + dest->g_y += tb_area.g_h; dest->g_h -= tb_area.g_h; } } else if (mode == GUIWIN_AREA_TOOLBAR) { - if (win->toolbar != NULL) { - if (win->flags & GW_FLAG_HAS_VTOOLBAR) { - dest->g_w = win->toolbar[win->toolbar_idx].ob_width; - } else { - dest->g_h = win->toolbar[win->toolbar_idx].ob_height; - } - } else { - dest->g_h = 0; - dest->g_w = 0; - } + if (win->toolbar) { + if (win->flags & GW_FLAG_HAS_VTOOLBAR) { + dest->g_w = win->toolbar[win->toolbar_idx].ob_width; + } else { + dest->g_h = win->toolbar[win->toolbar_idx].ob_height; + } + } + else { + dest->g_w = 0; + dest->g_h = 0; + } } } -void guiwin_scroll(GUIWIN *gw, short orientation, int units, bool refresh) + +/** +* Scroll the content area (GUIWIN_AREA_CONTENT) in the specified dimension +* (GUIWIN_VSLIDER, GUIWIN_HSLIDER) +* \param win The GUIWIN +* \param orientation GUIWIN_VSLIDER or GUIWIN_HSLIDER +* \param units the amout to scroll (pass negative values to scroll up) +* \param refresh Sliders will be updated when this flag is set +*/ +void guiwin_scroll(GUIWIN *win, short orientation, int units, bool refresh) { - struct guiwin_scroll_info_s *slid = guiwin_get_scroll_info(gw); + struct guiwin_scroll_info_s *slid = guiwin_get_scroll_info(win); int oldpos = 0, newpos = 0, vis_units=0, pix = 0; int abs_pix = 0; GRECT *redraw=NULL, g, g_ro; - guiwin_get_grect(gw, GUIWIN_AREA_CONTENT, &g); + guiwin_get_grectw(win, GUIWIN_AREA_CONTENT, &g); g_ro = g; if (orientation == GUIWIN_VSLIDER) { @@ -691,7 +740,7 @@ void guiwin_scroll(GUIWIN *gw, short orientation, int units, bool refresh) if(pix < 0 ) { // blit screen area: g.g_h -= abs_pix; - move_rect(gw, &g, 0, abs_pix); + move_rect(win, &g, 0, abs_pix); g.g_y = g_ro.g_y; g.g_h = abs_pix; redraw = &g; @@ -699,7 +748,7 @@ void guiwin_scroll(GUIWIN *gw, short orientation, int units, bool refresh) // blit screen area: g.g_y += abs_pix; g.g_h -= abs_pix; - move_rect(gw, &g, 0, -abs_pix); + move_rect(win, &g, 0, -abs_pix); g.g_y = g_ro.g_y + g_ro.g_h - abs_pix; g.g_h = abs_pix; redraw = &g; @@ -727,7 +776,7 @@ void guiwin_scroll(GUIWIN *gw, short orientation, int units, bool refresh) if(pix < 0 ) { // blit screen area: g.g_w -= abs_pix; - move_rect(gw, &g, abs_pix, 0); + move_rect(win, &g, abs_pix, 0); g.g_x = g_ro.g_x; g.g_w = abs_pix; redraw = &g; @@ -735,7 +784,7 @@ void guiwin_scroll(GUIWIN *gw, short orientation, int units, bool refresh) // blit screen area: g.g_x += abs_pix; g.g_w -= abs_pix; - move_rect(gw, &g, -abs_pix, 0); + move_rect(win, &g, -abs_pix, 0); g.g_x = g_ro.g_x + g_ro.g_w - abs_pix; g.g_w = abs_pix; redraw = &g; @@ -744,14 +793,19 @@ void guiwin_scroll(GUIWIN *gw, short orientation, int units, bool refresh) } if (refresh) { - guiwin_update_slider(gw, orientation); + guiwin_update_slider(win, orientation); } if ((redraw != NULL) && (redraw->g_h > 0)) { - guiwin_send_redraw(gw, redraw); + guiwin_send_redraw(win, redraw); } } +/** +* Refresh the sliders of the window. +* \param win the GUIWIN +* \param mode bitmask, valid bits: GUIWIN_VSLIDER, GUIWIN_HSLIDER +*/ bool guiwin_update_slider(GUIWIN *win, short mode) { GRECT viewport; @@ -766,6 +820,8 @@ bool guiwin_update_slider(GUIWIN *win, short mode) old_x = slid->x_pos; old_y = slid->y_pos; + // TODO: check if the window has sliders of that direction...? + if((mode & GUIWIN_VSLIDER) && (slid->y_unit_px > 0)) { if ( slid->y_units < (long)viewport.g_h/slid->y_unit_px) { size = 1000L; @@ -807,26 +863,48 @@ bool guiwin_update_slider(GUIWIN *win, short mode) return(false); } +/** +* Return the AES handle for the GUIWIN. +*/ short guiwin_get_handle(GUIWIN *win) { return(win->handle); } +/** +* Return the VDI handle for an GUIWIN. +*/ VdiHdl guiwin_get_vdi_handle(GUIWIN *win) { return(v_vdi_h); } +/** +* Returns the state bitmask of the window +*/ uint32_t guiwin_get_state(GUIWIN *win) { return(win->state); } + +/** +* Set and new event handler function. +*/ void guiwin_set_event_handler(GUIWIN *win,guiwin_event_handler_f cb) { win->handler_func = cb; } +/** +* Configure the window so that it shows an toolbar or at least reserves +* an area to draw an toolbar. +* \param win The GUIWIN +* \param toolbar the AES form +* \param idx index within the toolbar tree (0 in most cases...) +* \param flags optional configuration flags +*/ +//TODO: document flags void guiwin_set_toolbar(GUIWIN *win, OBJECT *toolbar, short idx, uint32_t flags) { win->toolbar = toolbar; @@ -837,20 +915,32 @@ void guiwin_set_toolbar(GUIWIN *win, OBJECT *toolbar, short idx, uint32_t flags) } } +/** +* Attach an arbitary pointer to the GUIWIN +*/ void guiwin_set_user_data(GUIWIN *win, void *data) { win->user_data = data; } +/** +* Retrieve the user_data pointer attached to the GUIWIN. +*/ void *guiwin_get_user_data(GUIWIN *win) { return(win->user_data); } +/** Get the scroll management structure for a GUIWIN +*/ struct guiwin_scroll_info_s *guiwin_get_scroll_info(GUIWIN *win) { return(&win->scroll_info); } +/** +* Get the amount of content dimensions within the window +* which is calculated by using the scroll_info attached to the GUIWIN. +*/ void guiwin_set_scroll_grid(GUIWIN * win, short x, short y) { struct guiwin_scroll_info_s *slid = guiwin_get_scroll_info(win); @@ -861,6 +951,12 @@ void guiwin_set_scroll_grid(GUIWIN * win, short x, short y) slid->x_unit_px = y; } + +/** Set the size of the content measured in content units +* \param win the GUIWIN +* \param x horizontal size +* \param y vertical size +*/ void guiwin_set_content_units(GUIWIN * win, short x, short y) { struct guiwin_scroll_info_s *slid = guiwin_get_scroll_info(win); @@ -871,6 +967,14 @@ void guiwin_set_content_units(GUIWIN * win, short x, short y) slid->y_units = y; } +/** Send an Message to a GUIWIN using AES message pipe +* \param win the GUIWIN which shall receive the message +* \param msg_type the WM_ message definition +* \param a the 4th parameter to appl_write +* \param b the 5th parameter to appl_write +* \param c the 6th parameter to appl_write +* \param d the 7th parameter to appl_write +*/ void guiwin_send_msg(GUIWIN *win, short msg_type, short a, short b, short c, short d) { @@ -888,6 +992,7 @@ void guiwin_send_msg(GUIWIN *win, short msg_type, short a, short b, short c, appl_write(gl_apid, 16, &msg); } +// TODO: rename, document and implement alternative (guiwin_exec_event) void guiwin_send_redraw(GUIWIN *win, GRECT *area) { short msg[8], retval; @@ -940,6 +1045,8 @@ void guiwin_send_redraw(GUIWIN *win, GRECT *area) //appl_write(gl_apid, 16, &msg); } +/** Attach an AES FORM to the GUIWIN, similar feature like the toolbar +*/ void guiwin_set_form(GUIWIN *win, OBJECT *tree, short index) { DEBUG_PRINT(("Setting form %p (%d) for window %p\n", tree, index, win)); @@ -949,6 +1056,8 @@ void guiwin_set_form(GUIWIN *win, OBJECT *tree, short index) win->form_idx = index; } +/** Checks if a GUIWIN is overlapped by other windows. +*/ bool guiwin_has_intersection(GUIWIN *win, GRECT *work) { GRECT area, mywork; @@ -971,6 +1080,8 @@ bool guiwin_has_intersection(GUIWIN *win, GRECT *work) return(retval); } +/** Execute an toolbar redraw +*/ void guiwin_toolbar_redraw(GUIWIN *gw, GRECT *clip) { GRECT tb_area, tb_area_ro, g; @@ -1003,7 +1114,8 @@ void guiwin_toolbar_redraw(GUIWIN *gw, GRECT *clip) } } - +/** Execute FORM redraw +*/ void guiwin_form_redraw(GUIWIN *gw, GRECT *clip) { GRECT area, area_ro, g; @@ -1044,6 +1156,8 @@ void guiwin_form_redraw(GUIWIN *gw, GRECT *clip) } +/** Fill the content area with white color +*/ void guiwin_clear(GUIWIN *win) { GRECT area, g; -- cgit v1.2.3