Monster Media 1994 #1

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1994 #1 / monster.zip / monster / PROG_GEN / DOS_GUI.ZIP / HELPFILE < prev next >

Wrap

Text File | 1994-01-11 | 31KB | 1,212 lines

1212 $Topic,Contents ^Help on Help^ ^Graphics Library's Capabilities^ ^Text Mode Functions^ ^Graphics Mode Functions^ ^Mouse Functions^ ^Entry Fields^ ^Pull Down Menu^ ^Button Functions^ ^Percent Bar Display^ ^Scroll Bar^ ^Window Functions^ ^Miscellaneous Functions^ ^How to Order Source Code^ $Topic,Help On Help To activate HELP press the F1 Key or use the pull down menu. The Help Screen is organized as a large file separated by different Help Topics. The file may be examined by scrolling or by selecting related topics; related topics are displayed in green. To select a related topic, simply click it with the mouse or press the TAB key several times until the topic is selected; then press Enter. Help Buttons : ^Contents^ : displays the Contents Screen Back : returns to the previous screen up to 300 levels Done : Exit Help Help is activated by a single^Help Function^from the library. $Topic,Help Function void help(char *title,char *helpfile,char *starting_topic) title : is the displayed title on the help window. helpfile : Hyper text help file. starting_topic : The topic to be shown on the startup screen. HELP FILE FORMAT : first line : the number of lines in the help file The rest of the file would be Help topics followed by help information. Note : Each help topic must be at least 21 lines apart. Anywhere in the help text another help topic may be displayed by enclosing the topic with\^ character. The information will be displayed in green and if clicked on, help function will display that topic. To get back to the original topic, use the BACK button. $Topic,Graphics Library's Capabilities The Plain Design GUI library is designed to function in the graphics mode while allowing programming using Text mode and graphics mode functions. You may easily convert a text mode program to graphics mode using this library. When using a text mode function, the screen will be 80 characters wide and 30 characters long. In graphics mode it is 640 * 480 pixels. $Topic,Text Mode Functions In text mode X coordinates are between 0-79 Y coordinates are 0-29 color is in the form of '0xbf' b=background : from 0 to F f=forground : from 0 to F Functions : ************************************************** * Draw a filled rectangle * ************************************************** void frect(int x1,int x2,int y1,int y2,int color); ************************************************** * Draw a rectangle * ************************************************** void rect(int x1,int x2,int y1,int y2,int color); ************************************************** * Draw a double line rectangle * ************************************************** void dl_rect(int x1,int x2,int y1,int y2,int color); ************************************************** * write a character at X,Y * ************************************************** void writechar (int x,int y,unsigned char c,int color); ************************************************** * write a character in window handle h * ************************************************** void writecharh(int x,int y,unsigned char c,int color,int h); ************************************************** * write a string starting at X,Y * ************************************************** void pls (int x,int y,char *string,int color); ************************************************** * write a string starting at X,Y of window h * ************************************************** void plsh (int x,int y,char *string,int color,int h); ************************************************** * read a character from location X,Y * ************************************************** unsigned char readchar (int x,int y); ************************************************** * read color of the character at X,Y * ************************************************** int readcolor (int x,int y); ************************************************** * read a string starting at X,Y and size length * ************************************************** void readstring(int x,int y,int size,char *string); ************************************************** * change color of the character block * ************************************************** void chcolor(int x,int y,int xsize,int ysize,int color); $Topic,Graphics Mode Functions Graphics mode functions operate independently from the text mode screen memory. When a text mode function is used to write a character at location XY , that character may be read later by using the 'readchar' and 'readcolor' functions. In graphics mode this is not possible. In graphics mode XY coordinates are : 0<=X<=639 0<=Y<=479 To convert graphic coordinates to text coordinates : Xgraphics=Xtext*font_width Ygraphics=Ytext*font_height Graphics Functions : ^Geometric Shapes^ ^Writting Text^ ^Saving / Restoring Pixel Blocks^ $Topic,Geometric Shapes Note: the functions that start with 'c' do not turn the graphics cursor off when drawing. The equivalent function that does not start with the letter c does turn the cursor off. Geometric Functions : ************************************************** * read or draw a pixel int coordinates XY * ************************************************** void SETPIX(int x,int y,char color); int GETPIX(int x,int y); int RSETPIX(int,int,int); /* XOR the color value */ ************************************************** * Draw a Line * ************************************************** void gr_line (int x1,int y1,int x2,int y2,int color); void cgr_line(int x1,int y1,int x2,int y2,int color); ************************************************** * Draw a Line XOR the color * ************************************************** void xor_line (int x1,int y1,int x2,int y2,int color) ************************************************** * Draw a graphics rectangle * ************************************************** void grect (int x1,int y1,int x2,int y2,int color); void cgrect(int x1,int y1,int x2,int y2,int color); ********************************************************* * Draw a rectangle with Width 'w' pixels, xor the color * ********************************************************* void xor_rect(int w,int x1,int y1,int x2,int y2,int color) ************************************************** * Draw a graphics filled rectangle * ************************************************** void gfillrect (int x1,int y1,int x2,int y2,int color); void cgfillrect(int x1,int y1,int x2,int y2,int color); ************************************************** * Draw a graphics filled rectangle XOR color * ************************************************** void xor_frect (int x1,int y1,int x2,int y2,int color) ************************************************** * Draw an ellipse * ************************************************** void ELLIPSE(int x,int y,int a,int b,int color); ************************************************** * Draw an ellipse cut at x1cut,y1cut,x2cut,y2cut * ************************************************** int PCELLIP(int x,int y,int a,int b, int x1cut,int y1cut, int x2cut,int y2cut, int color); ************************************************** * Same as PCELLIP, but XOR the color * ************************************************** int RCELLIP(int x,int y,int a,int b, int x1cut,int y1cut, int x2cut,int y2cut, int color); $Topic,Writting Text Graphics text functions are similar to Text mode functions, except that they do not alter the screen memory ( they cannot be read back ). The XY coordinates are the graphics coordinates while the color value is the same as their TEXT mode equivalent; void gwritechar(int gx,int gy,unsigned char c ,int color); void gpls (int gx,int gy,unsigned char *string,int color); void cgpls (int gx,int gy,unsigned char *string,int color); The following functions are the same as above except that the color value is between 0 and 15. These functions do not display a background color for text. void gwritechar2(int gx,int gy,unsigned char c ,int color); void gpls2 (int gx,int gy,unsigned char *string,int color); The following functions will XOR the color value void rgwritechar(int gx,int gy,unsigned char c ,int color); void rgpls2 (int gx,int gy,unsigned char *string,int color); $Topic,Saving / Restoring Pixel Blocks A block of pixels may be saved in memory and restored later. This function is used extensively by the pull down menu function, to restore the background of the menus after it is deactivated. *************************************************************** * Save a block of pixels in memory * *************************************************************** int GET_IMAGE(int x,int y,int xsize,int ysize,char far *m); note : before calling this function, the memory used must be allocated using farmalloc. The size of the required memory to be allocated is determined by get_block_size function. *************************************************************** * return size of the block required for GET_IMAGE function * *************************************************************** long get_block_size(int x1,int y1,int x2,int y2); *************************************************************** * Restore a block of pixels previously saved by GET_IMAGE * *************************************************************** void RESTORE_IMAGE(char far *m,int x1,int y1); $Topic,Mouse Functions When initdisplay is called, the mouse is initialized. The mouse routines in this library work by polling; they are not interupt driven. If in a loop area the mouse stops operating, add the line gcurs(MOVE); to the loop. This function will take care of all mouse movements. ***************************************************************** * read the location of the mouse : values are for graphics mode * * to convert to text divide by font_width and font_height vars * ***************************************************************** void get_ml(int *x,int *y); ********************************************************** * returns YES or NO for the status of the mouse left key * ********************************************************** int mouse_left_pressed(void); ********************************************************** * this function sets variables ms and dc for the status * * ms can be any values:PRESSED,RELEASED,PRESSEDRELEASED * * dc can be any of above values, but it could also * * become DOUBLECLICKED * ********************************************************** int mouse_state(void); ********************************************************** * Show mosue cursor * ********************************************************** void show_mouse_cursor(void); ********************************************************** * hide mosue cursor * ********************************************************** void hide_mouse_cursor(void); ********************************************************** * limit mouse movement * ********************************************************** void limit_mouse(int x1,int y1,int x2,int y2); $Topic,Entry Fields Entry fields may be a text field or a binary field. To edit a field, a field structure must be created first and passed to the field functions. ****************************************************************** * TEXT FIELD * ****************************************************************** int text_field(struct xfield *,int action); action : INIT /* initialize and display */ -2 /* edit */ struct xfield { int type; /* type of the field */ /* can be F_TEXT,F_DATE,F_TIME,F_TEL */ int x; /* field's X coordinate */ int y; /* field's Y coordinate */ int length; /* field length */ char title[20]; /* title of the field */ char f[80]; /* field content */ int fcolor; /* field color */ int tcolor; /* title color */ int xstart; /* default x location for the cursor */ }; ****************************************************************** * BINARY FIELD * ****************************************************************** int binary_field(&bfield,action,int h); action : INIT /* initialize and display */ -2 /* edit */ h : window handle or -1 for no window struct bfield { int x; /* x coordinate of the field */ int y; /* y coordinate of the field */ char title[54]; /* title of the field */ int fcolor; /* color of the field it selft */ int tcolor; /* color of the title of the field */ int content; /* set to yes or no */ }; $Topic,Pull Down Menu This library provides a very powerful pull down menu function. Pull Down Menus are implemented by a single function bar_menu. The pull down menu has a default behavior which may modified by calling the^Pull Down Menu Functions^. For simplicity use the default parameters first. The bar_menu function acts as a getkey function until the pull down menu is invoked. To add a pull down menu to your program you must first creat a menu descriptor file; a menu descriptor defines the pull down's titles and entries. To place a menu title in the pull down menu you must add the following line: "%Pull Down Title" id acc . Note that the title string starts with % . id is the value returned when the menu is activated . acc is a key code for an accelerator key for the menu for example if the title is for exit, you might want ALTX to also activate exit without having to use the menu, then acc should be the value for ALTX which is 301 To add entries under a title you must add lines as follows: "Entry 1" id1 acc1 "Entry 2" id2 acc2 .... When a title has entries associated to it, its id value is ignored, but the acc value will turn on the pull down menu starting with that title. Entry ids are the values returned when a menu entry is activated. When bar_menu senses an accelerator, it will automatically return the id associated to that accelerator without invoking the pull down menu. Note : accelerators are optional and may be omitted. To add a line between two entries simply add the word LINE as follows : "Entry 1" id1 acc1 LINE "Entry 2" id2 acc2 To add a submenu under an entry do as follows : "Entry 1" id1 acc1 SUBMENU "SubEntry1" subid1 subacc1 "SubEntry2" subid2 subacc2 END "Entry 2" id2 acc2 There is no limit to how many levels of submenus you may add in the menu descriptor file. To add the pull down menu to a program do as follows : bar_menu(INIT); while(1) { message=bar_menu(KEY_RETURN); } The bar_menu function by default looks for a descriptor file "MENUFILE". To change the menu file name use void ch_menu_filename(char *newfilename); After you are satisfied with the Pull Down Menu you have created, you can compile the menufile in your program by using the CT_VAR.EXE program. This program reads the menufile and creates a header file which can be included in your program. To make the bar_menu function look at the header file instead of a text file add the following function before initializing the bar_menu function. set_menu_descriptor(VARIABLE,menu_var,num_of_lines); CT_VAR names the menu variables as menu_var and num_of_lines; you may change those variable names, but make sure to change the names in the above function call also. $Topic,Pull Down Menu Functions ------------------------------------------------------------------ int bar_menu(int action); ------------------------------------------------------------------ The main entry to the drop down menu function. When action=INIT, the menu is initialized; when action=DISPLAY, the bar_menu will display the menu titles on the screen; when action=KEY_RETURN, the bar_menu function is in operational state. It will return EOF if no operation had taken place. RETURNS : Keyborard code, or menu definition number when selected EOF when there is no keyboard action. ------------------------------------------------------------------ NOTE : the following functions change the attributes of the colors used for the menu. All background function which start with bg_ can use the following background color values : BG_BLACK 0x00 BG_BLUE 0x10 BG_GREEN 0x20 BG_CYAN 0x30 BG_RED 0x40 BG_MAGENTA 0x50 BG_BROWN 0x60 BG_WHITE 0x70 All the forground function which start with fg_ can use the following forground color values : FG_BLACK 0x00 FG_BLUE 0x01 FG_GREEN 0x02 FG_CYAN 0x03 FG_RED 0x04 FG_MAGENTA 0x05 FG_BROWN 0x06 FG_WHITE 0x07 FG_GRAY 0x08 FG_LIGHT_BLUE 0x09 FG_LIGHT_GREEN 0x0A FG_LIGHT_CYAN 0x0B FG_LIGHT_RED 0x0C FG_LIGHT_MAGENTA 0x0D FG_LIGHT_YELLOW 0x0E FG_BRIGHT_WHITE 0x0F ------------------------------------------------------------------ void bg_menu_color(int color); ------------------------------------------------------------------ This function changes the background color of the menu rectangle and text. RETURNS : NONE ------------------------------------------------------------------ void fg_menu_color(int color); ------------------------------------------------------------------ This function changes the forground color of the menu rectangle and text. RETURNS : NONE ------------------------------------------------------------------ void bg_menu_hotkey_color(int color) ------------------------------------------------------------------ This function changes the background color of the menu hotkey letter. RETURNS : NONE ------------------------------------------------------------------ void fg_menu_hotkey_color(int color) ------------------------------------------------------------------ This function changes the forground color of the menu hotkey letter. RETURNS : NONE ------------------------------------------------------------------ void bg_menu_sel_color(int color) ------------------------------------------------------------------ This function changes the background color of the highlighted menu. RETURNS : NONE ------------------------------------------------------------------ void fg_menu_sel_color(int color) ------------------------------------------------------------------ This function changes the forground color of the highlighted menu. RETURNS : NONE ------------------------------------------------------------------ void bg_menu_shadow(int color) ------------------------------------------------------------------ This function changes the background color of shadow trailing the menu rectangle. RETURNS : NONE ------------------------------------------------------------------ void fg_menu_shadow(int color) ------------------------------------------------------------------ This function changes the forground color of shadow trailing the menu rectangle. RETURNS : NONE ------------------------------------------------------------------ void ch_menu_x(int x); ------------------------------------------------------------------ This function will change the x location of the menu bar. This function must be called before, the bar_menu is initialized. RETURNS : NONE ------------------------------------------------------------------ void ch_menu_xsize(int xsize); ------------------------------------------------------------------ This function will change the size of the menu bar. By default the menu bar will be extended across the screen. If a smaller menu bar is desired, use this function. This function must be called before, the bar_menu is initialized. RETURNS : NONE ------------------------------------------------------------------ void ch_menu_y(int y); ------------------------------------------------------------------ This function will change the y location of the bar menu. This function must be called before, the bar_menu is initialized. RETURNS : NONE ------------------------------------------------------------------ void set_menu_descriptor(int type,char **menu_variable, int num_of_lines ); ------------------------------------------------------------------ This function will allow to select the menu descriptor type, between TEXT_FILE and VARIABLE. By default the type is set to TEXT_FILE. To compile the menu descriptor in the program, run CT_VAR.EXE to convert the menu descriptor file to a header file. run set_menu_descriptor : type : VARIABLE or TEXT_FILE menu_variable : pointer to the array of pointers describing the menu descriptor. num_of_lines : number of entries in the menu_variable. If this function is being used to sert the descriptor RETURNS : NONE $Topic,Button Functions ******************************************************* * Draw a button at location XY with size xsize, ysize * ******************************************************* int draw_button(char *bstring,int x ,int y ,int xsize,int ysize, int id,int acc); bstring : string written inside of the button x,y : x,y location of the button in text coordinates to use graphics coordinates x=1000+xg where xg is in graphics coordinates y=1000+yg xsize : size of the button in graphics coordinates ysize id : value returned by check_button, when the button is invoked. acc : accelerator key code, when key pressed, id is retured. Returns : button handle ******************************************************* * Disable a button * ******************************************************* void disable_button(int h); ******************************************************* * Disable a button and paint the background color * ******************************************************* void disable_button2(int h,int color); *************************************************************** * Check button activity, If nothing return ch else it returns * * the button id * *************************************************************** int check_button(int ch); ********************************************** * deactivate or reactivate displayed buttons * ********************************************** void deactivate_activebuttons(void); void reactivate_activebuttons(void); $Topic,Percent Bar Display Displays a bar showing the percentage of Numerator / Denominator This function is useful is showing the progress of an action. int show_percent_bar( int a, // numerator int b, // denomnator int x, // bar x int y, // bar y int xw, // bar total width int yw, // bar total height int border_color, // bar border color int bar_color, // filled bar color int rev_num_color // color of the percent display ) The first time this function is called, a must be 0. At that time the function will initialize. When done, show_percent_bar must be called again with a=-1 to release the memory it allocated. $Topic,Scroll Bar The scroll bar function displays an adjustable bar. When adjusted, it changes a variable to show the level of adjustment that took place. If the variable is changed outside of the scroll bar function, it will readjust to show the new level. int scr_bar( int action, // INIT or ACTION int ch, // input character int maxnum, // maximum number for num int *num, // current level 0<=num<=maxnum int x1,int y1,int x2,int y2, // scroll bar coordinates int border_color, // scroll bar border color int bar_color, // bar color itself int key_sw // if ==-1 deactivate up,down // arrow functionality internal to // the scroll bar function. // if 0 it will scroll the bar up and // down when the arrows are pressed. ); $Topic,Window Functions The window functions of this library work in text mode coordinates. ********************************************** * draw a window while saving the background * ********************************************** wh=messagebox( int x,int y,int xsize,int ysize, // coordinates int color, // window color int shadow, // window shadow int border // window border YES or NO ); Returns : the window handle ********************************************** * Remove a window * ********************************************** void destroy_messagebox(int wh); $Topic,Miscellaneous Functions ****************************************************** * delay in milli second * ****************************************************** void delay_func(int milli); ****************************************************** * Return the key pressed, EOF when no action * ****************************************************** int getkey(void); ****************************************************** * Returns YES when alt key is pressed * ****************************************************** int alt_pressed(void); ****************************************************** * Set the video mode * ****************************************************** int set_video_mode(int); ****************************************************** * Get the video mode * ****************************************************** int get_video_mode(void); $Topic,How to Order Source Code Library Source Code for the GUI library is available for $29.00 + $5.00 S/H in US International orders add $10.00 S/H Send Check or Money Order Only to : Plain Design Inc. P.O. Box 135 Midland Park, NJ 07432 Please indicate the floppy size.