This section describes the new structures and constants used by the new functions found in Geneva. These are contained in XWIND.H. Note that all bitfields begin with the most significant bit first.
| Name | Type | Description |
|---|---|---|
| GENEVA_VER | constant | The Geneva version for which XWIND.H was last updated |
| GENEVA_COOKIE | constant | The cookie "Gnva" |
| G_COOKIE | typedef struc | Structure pointed to by the "Gnva" cookie |
| > ver | int | > Should contain GENEVA_VER |
| > process_name | char pointer | > Points to the name of the process currently using Geneva. This is in appl_find() format. |
| > apid | int | > Application ID of the process |
| > aes_funcs | pointer to array | > Internal table of AES functions |
| > xaes_funcs | pointer to array | > Internal table of extended functions |
| Name | Type | Description |
|---|---|---|
| SET_VER | constant | The current version returned in the SETTINGS structure |
| KEYCODE | typedef struct | Keypress description |
| > shift | unsigned char | > bit 0: Right Shift key
held > bit 1: Left Shift key held > bit 2: Control key held > bit 3: Alterna key held |
| > scan | unsigned char | > Scan code or zero |
| > ascii | unsigned char | > ASCII value or zero |
| OB_PREFER | typedef union | Extended object description |
|---|---|---|
| > s | struct | > Bitmapped flags |
| >> outlined | 1 bit | >> Object is OUTLINED |
| >> shadowed | 1 bit | >> Object is SHADOWED |
| >> draw_3D | 1 bit | >> Object is draw in 3D |
| >> rounded | 1 bit | >> Object has round corners |
| >> reserved | 12 bits | >> Reserved for future use |
| >> framecol | 4 bits | >> Color of frame |
| >> textcol | 4 bits | >> Color of text |
| >> textmode | 1 bit | >> 0: transparent, 1: replace |
| >> fillpattern | 3 bits | >> Fill pattern index |
| >> interiorcol | 4 bits | >> Color of interior |
| > l | unsigned long | > Longword for accessing all flags |
| SETTINGS | typedef struct | Describes Geneva's global settings |
| > version | int | > Version SETTINGS is for, in BCD |
| > struct_len | int | > Total # of bytes in SETTINGS |
| > boot_rez | int | > ST/TT resolution at startup |
| > falcon_rez | int | > Falcon video mode at startup |
| > flags | union | > Preferences |
| >> s | struct | >> Bitmapped flags |
| >>> pulldown | 1 bit | >>> 1: use pulldown menus |
| >>> insert_mode | 1 bit | >>> 1: insert in dialog edits |
| >>> long_titles | 1 bit | >>> long underlines X_UNDERLINE |
| >>>alerts_under_mouse | 1 bit | >>> alerts appear under mouse |
| >>> fsel_1col | 1 bit | >>> 1 column in Item Selector |
| >>> grow_shrink | 1 bit | >>> 1: FMD_GROW/SHRINK on |
| >>>ear_always_topped | 1 bit | >>> 1: tear aways always usable |
| >>> reserved | 9 bits | >>> Reserved for future use |
| >> i | unsigned int | >> Word for accessing all flags |
| > gagdet_pause | int | > # of 50 Hz timer tics to wait |
| > menu_start | KEYCODE | > Key to start menus |
| > app_switch | KEYCODE | > Key to toggle between apps |
| > ascii_table | KEYCODE | > Key to open ASCII table |
| > redraw_all | KEYCODE | > Key to redraw whole screen |
| > wind_keys[13] | KEYCODE | > Keys for window events |
| > color_3D[4] | OB_PREFER | > Colors for 3D objects |
| > color_root[4] | OB_PREFER | >> Colors for root objects |
| > color_exit[4] | OB_PREFER | > Colors for EXIT objects |
| > color_other[4] | OB_PREFER | > Colors for other objects |
| > sort_type | char | > fsel sort type, 0(Name) - 4(None) |
| > find_file[26] | char | > fsel Search string td> |
| > fsel_path[10][35] | char | > Item Selector paths |
| > fsel_ext[10][6] | char | > Item Selector extension strings |
| XS_UPPAGE | constant | Index for up page key |
| XS_DNPAGE | constant | Index for down page key |
| XS_UPLINE | constant | Index for up line key |
| XS_DNLINE | constant | Index for down line key |
| XS_LFPAGE | constant | Index for page left key |
| XS_RTPAGE | constant | Index for page right key |
| XS_LFLINE | constant | Index for line left key |
| XS_RTLINE | constant | Index for line right key |
| XS_CLOSE | constant | Index for close box key |
| XS_CYCLE | constant | Index for cycle window key |
| XS_FULL | constant | Index for full window key |
| XS_LFINFO | constant | Index for info left key |
| XS_RTINFO | constant | Index for info right key |
| X_SHLOADSAVE | constant | x_shel_get/put load/save SETTINGS |
| X_SHOPEN | constant | x_shel_get/put start read/write |
| X_SHACCESS | constant | x_shel_get/put do read/write |
| X_SHCLOSE | constant | x_shel_get/put close |
| WIND_TREE | typedef struct | Structure for x_wind_tree |
| > handle | int | > Handle of window being modified |
| > count | int | > Number of objects in window |
| > flag | int | > Location to copy to/from |
| X_WT_GETCNT | constant | x_wind_tree get count and flag |
| X_WT_READ | constant | x_wind_tree copy window tree |
| X_WT_SET | constant | x_wind_tree set new tree |
| X_WTFL_RESIZE | constant | Auto resize |
| X_WTFL_CLICKS | constant | Process clicks |
| X_WTFL_SLIDERS | constant | Resize sliders, info |
| X_WTFL_BLITSCRL | constant | Use blit for realtime scroll |
| WGCLOSE | constant | Closer gadget |
| WGMOVE | constant | Mover |
| WGICONIZ | constant | Smaller (iconify) |
| WGBACK | constant | Send to back |
| WGFULL | constant | Fuller |
| WGILEFT | constant | Info left |
| WGINFO | constant | Info |
| WGIRT | constant | Info right |
| WGTOOLBOX | constant | Tool bar |
| WGMNLEFT | constant | Menu left |
| WGMENU | constant | Menu |
| WGMNRT | constant | Menu right |
| WGUP | constant | Up arrow 1 |
| WGVBIGSL | constant | Vertical scroll bar 1 |
| WGVSMLSL | constant | Vertical slider 1 |
| WGDOWN | constant | Down arrow 1 |
| WGVSPLIT | constant | Vertical split bar |
| WGUP2 | constant | Up arrow 2 |
| WGVBIGSL2 | constant | Vertical scroll bar 2 |
| WGVSMLSL2 | constant | Vertical slider 2 |
| WGDOWN2 | constant | Down arrow 2 |
| WGLEFT | constant | Left arrow 1 |
| WGHBIGSL | constant | Horizontal scroll bar 1 |
| WGHSMLSL | constant | Horizontal slider 1 |
| WGRT | constant | Right arrow 1 |
| WGHSPLIT | constant | Horizontal split bar |
| WGLEFT2 | constant | Left arrow 2 |
| WGHBIGSL2 | constant | Horizontal scroll bar 2 |
| WGHSMLSL2 | constant | Horizontal slider 2 |
| WGRT2 | constant | Right arrow 2 |
| WGSIZE | con1more than five lines of 30 characters each, and the pre-defined error messages can take up to three lines, there should be no more than two lines of text surrounding the inserted error text.
Example:
if( x_form_error( "[1][Error!|%s][Continue|Quit]", -33 ) == 1 )
continue...
else quit...
beginning of section top of page Convert to/from a standard GEMDOS filename in editable field in a dialog.
control[0] = $7112
control[1] = 2
control[2] = 1
control[3] = 2
control[4] = 0
intin[0] = obj Index of the editable object in the tree
intin[1] = to_from Convert to (0) or from (1) the field
intout[0] = xff_return Always 1
addrin[0] = tree Object tree of the dialog containing
the editable field
addrin[1] = string Pointer to the string containing the
GEMDOS-formatted (FILENAME.EXT) string.
Since filenames are typically entered in a GEM dialog using the period to separate the filename from the extension, and filenames with less than eight characters before the period are padded with spaces, converting to and from the editable field can be a difficult task. When the mode parameter passed to x_form_filename() is 0, the string is converted from the FILENAME.EXT format to the editable field format. When mode is 1, the filename is converted from the editable field and written into string in FILENAME.EXT format. Note that this function assumes that the editable field is an object of type G_FTEXT or G_FBOXTEXT and uses the te_ptmplt string "________.___". Example: OBJECT *tree; char name[13] = "DEFAULT.TXT"; x_form_filename( tree, object, 0, name ); form_do( tree, object ); x_form_filename( tree, object, 1, name ); /* "name" now contains what the user changed it to */ beginning of section top of page 26.6.9 xfm_return = x_form_mouse( OBJECT *tree, int mouse_x, int mouse_y, int clicks, int *edit_obj, int *next_obj, int *edit_idx )Handle mouse clicks in a dialog, including editable cursor movement. control[0] = $7113 control[1] = 6 control[2] = 4 control[3] = 1 control[4] = 0 intin[0] = mouse_x X coordinate of the mouse pointer intin[1] = mouse_y Y coordinate of the mouse pointer intin[2] = clicks Number of clicks to be processed intin[3] = edit_obj Object currently having the edit cursor intin[4] = next_obj Object selected with the mouse intin[5] = edit_idx Position of edit cursor within field intout[0] = xfm_return 0: An object was selected, 1: No object intout[1] = edit_obj New object having the edit cursor intout[2] = next_obj Selected object, or 0 for none intout[3] = edit_idx New edit cursor position addrin[0] = tree This function begins by calling form_button(). If neither an EXIT nor a TOUCHEXIT button is selected, and the object is EDITABLE, then the editable cursor is moved to the character within the editable field which is under the mouse pointer.
26.6.10 xfs_return = x_fsel_input( char *inpath, int pathlen, char *files, int sels, int *exbutton, char *label )Extended file selector.
control[0] = $7120
control[1] = 2
control[2] = 2
control[3] = 3
control[4] = 0
intin[0] = pathlen Maximum length (incl. null) of inpath
intin[1] = sels Maximum number of items that can be
selected upon return from the call
intout[0] = xfs_return 0: An error occurred
intout[1] = exbutton 0: The user selected Cancel
1: The user selected OK
addrin[0] = inpath Pointer to the path (with wildcards)
to start selection at
addrin[1] = files Pointer to the string containing the
default filename to be displayed.
Also,
holds up to "sels" filenames (each
null-terminated) upon return.
addrin[2] = label A label of up to 30 characters, which
will appear at the top of the item selector.
This function is similar to fsel_exinput(), but has several extensions:
beginning of section to bof page 26.6.11 xgb_return = x_graf_blit( GRECT *source, GRECT *dest )Blit one area of the screen to another location, or save/restore a block of screen data.
control[0] = $7130
control[1] = 0
control[2] = 1
control[3] = 2
control[4] = 0
intout[0] = xgb_return 0: Not enough memory for data to be
stored
1: No error
addrin[0] = source Address of source rectangle or NULL
addrin[1] = dest Address of destination rectangle or NULL
If source and dest are both non-zero, then the function simply blits the screen data from one rectangle to the other. If dest is NULL, then the operation saves the area of the screen specified by source in its internal buffer. When the function ise=ater called with source NULL and dest properly set, it will restore the area in the (new) location. The internal buffer is large enough to hold 1/2 of the current screen. Exceeding this will cause Geneva to try to allocate enough memory to hold the screen data. If this fails, a zero will be returned in xgb_return. Since this buffer is also used by Geneva to hold the screen data for alerts and menus, and also by the item selector, you should always surround code which uses x_graf_blit() with wind_update() calls. This example displays a dialog and uses a blit to restore what was underneath it:
OBJECT *tree;
GRECT r;
rsrc_gaddr( 0, 0, &tree ); /* get dialog */
form_center( tree, &r.g_x, &r.g_y,
&r.g_w, &r.g_h ); /* center it */
wind_update( BEG_UPDATE ); /* lock menu bar */
graf_blit( &r, 0L ); /* save what's there */
objc_draw( tree, 0, 8, r.g_x,
r.g_y, r.g_w, r.g_h ); /* draw dialog */
form_do( tree, 0 ); /* get user response */
graf_blit( 0L, &r ); /* now restore */
wind_update( END_UPDATE ); /* re-enable menus */
beginning of section top of page 26.6.12 xgr_return = x_graf_rubberbox(GRECT *area, GRECT *outer, int minwidth, int minheight, int maxwidth, int maxheight, int snap, int lag )Extended rubberband box drawing.
control[0] = $7131
control[1] = 6
control[2] = 1
control[3] = 2
control[4] = 0
intin[0] = minwidth Minimum width of the rubberband box
intin[1] = minheight Minimum height of the box
intin[2] =enaxwidth Maximum width of the box
intin[3] = maxheight Maximum height of the box
intin[4] = snap Width/height increment
intin[5] = lag 0: Follow mouse exactly
1: Move relative to initial width & height
intout[0] = xgr_return 0: The mouse was released prematurely
1: No error
addrin[0] = area Initial size of the rubberband box
addrin[1] = outer Outer limit of the rubberband box
This function is similar to the AES function graf_rubberbox(), but it offers several extensions.
beginning of section top of page 26.6.13 xoe_return = x_objc_edit( OBJECT *tree, int edit_obj, int key_press, int shift_state, int *edit_idx, int mode )Process keyboard input into an editable field, with extensions.
control[0] = $7140
control[1] = 5
control[2] = 2
control[3] = 1
control[4] = 0
intin[0] = edit_obj Object being edited
intin[1] = key_press Scan code and ASCII value of the key
intin[2] = edit_idx Current cursor position within field
intin[3] = shift_state bit 0: R-Shift,
1: L-Shift,
2: Control
intin[4] = mode 1: initialize,
2: edit,
3: end edit
intout[0] = xoe_return 0: not an editable field,
1: no error
intout[1] = edit_idx New cursor position
addrin[0] = tree OBJECT tree containing editable field
This function is nearly identical to the objc_edit() function normaly found in GEM. By adding the shift_state, however, it is able to correctly process extended keystrokes involving the [Control] and [Shift] keys.
26.6.14 xwd_return = x_wdial_draw( int handle, int start, int depth )Redraw a dialog within a window.
control[0] = $7150
control[1] = 3
control[2] = 1 control[3] = 0
control[4] = 0
intin[0] = handle Handle of the window having the dialog
intin[1] = start First object to draw
intin[2] = depth Level to draw until:
0: Draw just the object
1: Draw object & its immediate children
...
8: Draw all levels of children
intout[0] = xwd_return 0: An error occurred
This function will redraw a dialog contained within a window. The dialog must have previously been set using the wind_set() option X_WF_DIALOG. The dialog is redrawn, starting at start, continuing for depth levels, taking into account any other windows which may overlap the one being drawn. An error code is returned if either the handle specified is not a valid window handle, if the window does not belong to the application making the x_wdial_draw() call, if the window does not contain a dialog, or if the window is not currently open.
26.6.15 xwc_return = x_wdial_change( int handle, int object, int newstate )Redraw one object within a window dialog, showing a new state. control[0] = $7151 control[1] = 3 control[2] = 1 control[3] = 0 control[4] = 0 intin[0] = handle Handle of the window having the dialog intin[1] = object Object whose state is changing intin[2] = newstate The object's new ob_state intout[0] = xwc_return 0: An error occurred This function will redraw an object in a dialog contained within a window, showing its new state. This is commonly used to show an exit button being selected or another button becoming disabled. The dialog must have previously been set using the wind_set() option X_WF_DIALOG. An error code is returned if either the handle specified is not a valid window handle, if the window does not belong to the application making the x_wdial_draw() call, if the window does not contain a dialog, or if the window is not currently open.
26.6.16 xwcr_return = x_wind_create( int kind, int xkind, int wx,bunt wy, int ww, int wh )Extended wind_create(). control[0] = $7153 control[1] = 6 control[2] = 1 control[3] = 0 control[4] = 0 intin[0] = kind Window type (ala wind_create()) intin[1] = xkind Extended window type intin[2] = wx Window x-coordinate intin[3] = wy Window y-coordinate intin[4] = ww Window width intin[5] = wh Window height intout[0] = xwcr_return 0: An error occurred If you wish to use new or extended functions such as the X_MENU or split window attributes, then x_wind_create() must be used to create these windows.
26.6.17 xwca_return = x_wind_calc( int type, int kind, int xkind, int inx, int iny, int inw, int inh, int *outx, int *outy, int *outw, int *outh )Extended wind_calc(). control[0] = $7154 control[1] = 7 control[2] = 5 control[3] = 0 control[4] = 0 If you wish to use new or extended functions such as the X_MENU or split window attributes, then x_wind_create() must be used to create these windows.
26.6.18 xwt_return = x_wind_tree( int mode, WIND_TREE *wtree )Get or alter a window's OBJECT tree and gadget control flags.
control[0] = $7152
control[1] = 1
control[2] = 1
control[3] = 1
control[4] = 0
intin[0] = mode 0: Get count & flags, 1: Read tree,
2: Set count & flags
intout[0] = xwt_return 0: An error occurred
addrin[0] = wtree Pointer to a WIND_TREE structure
This function alters the way in which Geneva draws and processes the gadgets of a particular window. This allows a program to take control over how gadgets react to the mouse, and also to add new gadgets. The gadgets that make up a window are really just another OBJECT tree. This function allows you to modify it by (optionally) reading the current tree into a block of your program's memory. Geneva can then be informed that the modified tree (or, for that matter, any OBJECT tree) should be used for the window gadgets. Note:This function will only affect windows which have already been created. If all you need to do in your program is to change the fill patterns or colors of a gadget, it is better to use wind_set( WF_COLOR ) to accomplish this task, if possible.
26.6.18.1. Mode 0, X_WT_GETCNT (get count & flags)This mode must be used prior to mode 1. It sets the count element of the structure pointed to by wtree to contain the number of OBJECTS that make up the bendow's tree. The tree element is unchanged.
26.6.18.2. Mode 1, X_WT_READ (Read the current tree into the program's memory)This mode copies count OBJECTS of the window's current tree into the array of OBJECTS pointed to by the tree element. The area of memory MUST be large enough to hold count elements. Note that any objects in the resulting tree which have the HIDETREE ob_flag set are inactive, and their sizes and locations may be inaccurate. If the tree which was being copied was the default OBJECT tree used by Geneva, then the ob_spec fields of the second (WGMOVE) and seventh (WGINFO) OBJECTS in the resulting copy will be zero. If this tree is then set (using mode 2, below), and the X_WTFL_RESIZE bit is on, then the programmer MUST modify these ob_spec's to point to TEDINFO structures! Otherwise, Geneva will attempt to set the title and info text in bad memory locations.
26.6.18.3. Mode 2, X_WT_SET (Set count, flags, and tree address)This mode changes the attributes. If count is not less than zero, the window's OBJECT tree and count of objects will be set. The tree element must point to a static area of memory containing an OBJECT tree. The flags are always set, regardless of count. The following bits are defined in the flags element. By default, they are all set (turned on) for any window that is created. Undefined bits are reserved for future use and should not be modified.
Example:
/* Get the tree for a window, and change the appearence of
the up and down arrows */
TEDINFO info_ted, mover_ted;
OBJECT *tree
WIND_TREE wt;
int handle;
/* Create a window */
if( (handle = wind_create( UPARROW|DNARROW|VSLIDE, 20, 20,
200, 200 )) != 0 )
{
/* Get the current count and flags */
wt.handle = handle; x_wind_tree( X_WT_GETCNT, &wt );
/* Now allocate enough memory to hold the entire tree */
if( (tree = Malloc( wt.count*sizeof(OBJECT) )) != 0 )
{
/* And get the tree */
wt.tree = tree;
x_wind_tree( X_WT_READ, &wt );
/* Now, we *must* set these two TEDINFO's. The contents of the
TEDINFO's is not important because the info and mover bars
are not used */
tree[WGMOVE].ob_spec.tedinfo = &mover_ted;
tree[WGINFO].ob_spec.tedinfo = &info_ted;
/* Modify the arrows. The up arrow will now be a '^' character,
and the down arrow will be a 'v' */
tree[WGUP].ob_spec.bfobspec.character = '^';
tree[WGDOWN].ob_spec.bfobspec.character = 'v';
x_wind_tree( X_WT_SET, &wt );
/* All done! The window can be opened now, but don't forget to
Mfree(tree) later on when it's closed. */
}
}
beginning of section top of page 26.6.19 xs_return = x_settings( int getset, int length, SETTINGS *user )Get or set Geneva's internal settings. control[0] = $7180 control[1] = 2 control[2] = 1 control[3] = 1 control[4] = 0 intin[0] = getset 0 for Get, 1 for Set, -1 for Reset intin[1] = length # of bytes to get or set intout[0] = xs_return Always 1 addrin[0] = user Points to SETTINGS to get or set, or NULL beginning of section top of page 26.6.19.1. "getset" mode:
Example: SETTINGS set; x_settings( 0, sizeof(set), &set );
Example: Temporarily disable pulldowns: SETTINGS set; x_settings( 0, sizeof(set), &set ); /* get current */ set.pulldown = 0; x_settings( 1, sizeof(set), &set ); /* turn off */ ... /* do some stuff here */ set.pulldown = 1; x_settings( 1, sizeof(set), &set ); /* turn back on */
This function always returns 1.
26.6.20 xsg_return = x_shel_get( int mode, int length, char *buf )Read information from GENEVA.CNF.
control[0] = $7181
control[1] = 2
control[2] = 1
control[3] = 1
control[4] = 0
intin[0] = mode -1: Re-read Geneva's settings
0: Open GENEVA.CNF
1: Read a line
2: Close GENEVA.CNF
intin[1] = length Number of bytes to read into "buf"
intout[0] = xsg_return-3: Incorrect GENEVA.CNF version
(mode -1)
-2: disk error
-1: Already in use (mode 0)
0: End of data or string not found
1: No error
addrin[0] = buf Product string (mode 0) or buffer to
read "length" bytes of data into
(mode 1)
This function will cause Geneva to either re-read all of its own internal settings, or read the settings from an outside program's portion of GENEVA.CNF. When mode is X_SHLOADSAVE (-1), Geneva will re-read all of its internal settings. The length and buf parameters are not used in this mode. The Task Manager's "Load Settings" option uses this. In order to read its own settings, a program must begin by using mode X_SHOPEN (0) to open GENEVA.CNF. The name passed in buf can contain any character (including uppercase and punctuation) except the [ or ] characters. The length parameter is not used in this mode. If the X_SHOPEN was successful, the program can then make repeated calls using the X_SHACCESS (1) mode. Here, length specifies the maximum number of bytes to read into the string buffer buf. The x_sscanf() function is very helpful for retreiving formatted data that has been read with x_shel_get(); If an error occurs at any time during the open or read phases (or if the program's section of GENEVA.CNF ends), the file is automatically closed. If a program wants to end the reading sooner, it must use mode X_SHCLOSE (2) to close the file. Otherwise, any future attempts to read from the file will fail. Example:
int sh_error( int err )
{
switch(err) { case -2:
Cconws( "Disk error" );
return 1;
case -1:
Cconws( "GENEVA.CNF is already in use by another program" );
return 1;
case 0:
Cconws( "Read failed unexpectedly" );
return 1;
default:
return 0;
}
}
main() {
char buffer[100];
int version, number1, number2;
if( !sh_error( x_shel_get(X_SHOPEN,0,"My Program") ) )
if( !sh_error( x_shel_get(X_SHACCESS,sizeof(buffer),buffer) ) )
{
x_sscanf( buffer, "%v", &version );
if( version != 0x200 ) {
Cconws( "Not compatible with version 2.0!" );
x_shel_get( X_SHCLOSE, 0, 0L );
return;
}
if( !sh_error( x_shel_get(X_SHACCESS,sizeof(buffer),
buffer) ) )
x_sscanf( buffer, "%x %d", number1, number2 );
x_shel_get( X_SHCLOSE, 0, 0L );
}
}
beginning of section top of page 26.6.21 xsp_return = x_shel_put( int mode, char *buf )Save a program's own settings, or Geneva's settings, to GENEVA.CNF.
control[0] = $7182
control[1] = 1
control[2] = 1
control[3] = 1
control[4] = 0
intin[0] = mode -1: Save Geneva's settings
0: Open GENEVA.CNF
1: Write a line
2: Close GENEVA.CNF
intout[0] = xsp_return -2: Disk error
-1: Already in use (mode 0)
0: File not open or incorrect mode
1: No error
addrin[0] = buf Null-terminated string to write
When mode is X_SHLOADSAVE (-1), Geneva will save all of its internal settings. The length and buf parameters are not used in this mode. The Task Manager's Save Settings option uses this. In order to save its own settings, a program must begin by using mode X_SHOPEN (0) to open GENEVA.CNF. The name passed in buf can contain any character (including uppercase and punctuation) except the [ or ] characterli The length parameter is not used in this mode. If the X_SHOPEN was successful, the program can then make repeated calls using the X_SHACCESS (1) mode. Here, buf points to a null-terminated string to write. The string should be no more than 80 characters of readable text, and must not include the [ or ] characters. If the first character of the string is a semi-colon ";", it will be treated as a comment when read by x_shel_get(). The x_sprintf() function is very helpful for formatting data for x_shel_put(); If an error occurs at any time during the open or write phases the file is automatically closed. If no errors occur, the program must use mode X_SHCLOSE (2) to close the file. Otherwise, any future attempts to write to the file will fail.
26.6.22 void x_sprintf( char *buf, char *fmt, ... )Print data to a string, with extended formats. control[0] = $7183 control[1] = 0 control[2] = 0 control[3] = 3 control[4] = 0 addrin[0] = buf Buffer to receive output string addrin[1] = fmt Null-terminated format string addrin[2] = &... Pointer to first argument on user stack This function acts almost identically to the sprintf() function found in C programming libraries. It understands the following format specifiers:
%c Character
%s String
%x Unsigned int in hexadecimal
%X Unsigned long in hexadecimal
%d Signed int in decimal
%D Signed long in decimal
%o Signed int in octal
%b Boolean: 'F' for 0, or 'T' for non-zero
%k When passed a pointer to a KEYCODE structure, output all
three elements using the format "%02x %02x %02x"
%v Take the int argument and output the MSB and LSB in the
format "%x.%02x". Used for generating version numbers.
%S Surround the string with curly braces, so that a string
containing spaces can be read back in correctly with the x_sscanf() function
%h Same as %x
These prefixes can be used before the string and number formats:
- Left-justified, instead of right-justified
0 Pad with 0's insteausof spaces
0-9 Any number of digits (following a possible first '0' for padding)
specify the field length, in decimal
Example: Result:
x_sprintf( str, "%04x", 0xFE ); 00FE
x_sprintf( str, "%-06s", "Hi!" ); Hi!000
x_sprintf( str, "%6s", "Hi!" ); Hi!
x_sprintf( str, "%b %v", 2, 0x502 ); T 5.02
x_sprintf( str, "%S %s", "a b", "c d" ); {a b} c d
KEYCODE key = { 1, 0, 'X' };
x_sprintf( str, "key=%k", &key ); keyd 1 00 58
This sort of thing doesn't really belong in a GUI, but it made sense to include it, since it is used by Geneva internally, anyway.
26.6.23 void x_sscanf( char *buf, char *fmt, ... )Read formatted data from a string, with extended formats. control[0] = $7184 control[1] = 0 control[2] = 0 control[3] = 3 control[4] = 0 addrin[0] = buf Buffer containing data addrin[1] = fmt Null-terminated format string addrin[2] = &... Pointer to first argument on user stack This function acts almost identically to the sscanf() function found in C programming libraries. It understands the following format specifiers:
%c Character
%s String
%x Unsigned int in hexadecimal
%X Unsigned long in hexadecimal
%d Signed int in decimal
%D Signed long in decimal
%o Signed int in octal
%b Boolean into char: 0 for 'F', or 1 for 'T'
%k When passed a pointer to a KEYCODE structure, scan all three
elements using the format "%x %x %x"
%v Scan for the MSB and LSB of an int using the format
"%x.%x". Used for reading version numbers.
%S String surrounded with curly braces. This allows a string
containing spaces to be read back in as one string.
%h Unsigned char in hexadecimal
The x_sscanf() function does not understand any format prefixes.
Example: Result:
int i;
char str[10], str2[10], bool;
KEYCODE key;
x_sscanf( "FE", "%x", &i ); i = 0xFE
x_sscanf( "Hi!", "%s", str ); str = "Hi!"
x_sscanf( "T 5.02", "%b %v", &bool, &i ); bool = 1, i = 0x502
x_sscanf( "{a b} c", "%S %s", str, str2 ); str = "a b", str2 = "c"
x_sprintf( "01 00 58", "%k", &key ); key = { 1, 0, 58 };
This sort of thing doesn't really bong in a GUI, but it made sense to include it, since it is used by Geneva internally, anyway.
26.6.24 xhe_return = x_help( char *topic, char *helpfile, int sensitive )Inform the Help display program of a request for help text.
control[0] = $7185
control[1] = 1
control[2] = 1
control[3] = 2
control[4] = 0
intin[0] = sensitive 0: "topic" is not case-sensitive
intout[0] = xhe_return 0: an error occurred
addrin[0] = topic Help topic to search for
addrin[1] = helpfile GEMDOS file name to search first
for the help topic, or NULL to
search only GENEVA.HLP.
This function is used by a program to provide online help for its features. Geneva begins by checking to see if the help display program is already in memory. If it is not, then it is loaded from disk by way of the SHOWHELP environmental variable, as set in GEM.CNF. Once the program is in memory, it is sent a message containing the values passed in the x_help() function call. The user is then either shown the help text, or an error message saying that the topic was not found. The topic parameter points to a NUL-terminated string containing the help topic to search for. If sensitive is non-zero, then the case (upper/lower) of the topic must exactly match what is stored in the help file. If, however, sensitive is zero, both the case-sensitive and case-insensitive sections of the help file are searched for the topic. filename points to a NUL-terminated string describing the path and file name of the default help file to search for the topic. If no path information is used, then the PATH environmental variable is searched (by way of shel_find()) for the file. If this file is not found, or the topic is not found in the file, the user receives an error message. If filename is NULL (0L), then the topic is only searched for in GENEVA.HLP. An error code is returned if either the help program could not be loaded, or there was insufficient free memory to send the message.
|