home *** CD-ROM | disk | FTP | other *** search
/ Windoware / WINDOWARE_1_6.iso / source / toolbar / toolbar.doc < prev    next >
Text File  |  1991-07-28  |  7KB  |  164 lines
  1. DOCUMENTATION ON THE TOOLBAR LIBRARY
  2. ====================================
  3.  
  4. by Stephen Chung (stephenc@cunixf.cc.columbia.edu)
  5.  
  6.  
  7. Introduction
  8. ------------
  9.  
  10. This set of routines implement the slick "toolbar" found in Microsoft
  11. Word for Windows, Excel etc.  They are written and compiled using
  12. Borland C++ 2.0.  I HAVE NOT tested them on any other compiler.
  13.  
  14.  
  15. How to use
  16. ----------
  17.  
  18. Look at the sample program TBTEST.C for an example.  That toolbar is
  19. part of a Japanese word processor I am writing.  I have not included
  20. the icons because they are embedded in a large .res file with everything
  21. else.  If you want some of them, send me email.
  22.  
  23. First of all, the toolbar is a 3-dimensional, horizontal bar containing
  24. "toolbar buttons".  You can add other kinds of child window controls
  25. onto the toolbar as well, such as combo boxes etc.
  26.  
  27. Before you do anything, you must define an array of TOOLBARICON.  Each
  28. element in that array corresponds to one toolbar button.  The fields
  29. should be set according to the followoing:
  30.  
  31.     int id                  /* The numeric ID of the button (0-255) */
  32.     int x, y                /* The X,Y position of the button, in pixels */
  33.     int width, height       /* The width/height of the button, in pixels */
  34.     int state               /* The initial state of the button:
  35.                                     -1 = Disabled
  36.                                      0 = Off
  37.                                      1 = On
  38.                                      2 = Grayed
  39.                             */
  40.     int cycle               /* The mode of that button, upon a mouse click:
  41.                                      0 = Leave the state alone
  42.                                            (Set it with a BM_SETSTATE message)
  43.                                      1 = Always undepressed, but flashed once
  44.                                      2 = Toggle On --> Off --> On
  45.                                      3 = Toggle On --> Off --> Gray --> On
  46.                             */
  47.  
  48.     char *disabled          /* The name for the DISABLED bitmap */
  49.     char *undepressed       /* The name for the OFF bitmap */
  50.     char *depressed         /* The name for the ON bitmap */
  51.     char *grayed            /* The name for the GRAYED bitmap */
  52.     char *pressing          /* The name for the bitmap for being pressed */
  53.  
  54. You should leave the rest of the fields alone.  They are used internally
  55. by the routines.
  56.  
  57. To create the toolbar, call CreateToolbar.  This routine has the following
  58. parameters:
  59.  
  60.     HWND CreateToolbar (HWND parent, int x, int y, int width, int height,
  61.                         int thickness, int id, int nr_buttons, HANDLE hInstance,
  62.                         TOOLBARICON *icons, char *xcursor)
  63.  
  64.  
  65.     HWND parent             /* The parent window handle */
  66.     int x, y,               /* X,Y position of the toolbar, in pixels */
  67.     int width, height       /* Width and height, in pixels */
  68.     int thickness           /* Its apparant thickness, in pixels */
  69.     int id                  /* ID number */
  70.     int nr_buttons          /* The number of toolbar buttons */
  71.     HANDLE hInstance        /* Instance handle */
  72.     TOOLBARICON *icons      /* Pointer to a TOOLBARICON array */
  73.     char *xcursor           /* The name of the cursor for a disabled toolbar
  74.                                button.  If NULL, the cursor will remain an
  75.                                arrow */
  76.  
  77. The routine will return the handle for the toolbar.  You can use this handle
  78. to add more child controls (see TBTEST.C).
  79.  
  80. The toolbar will send a WM_COMMAND message to its parent when one of its
  81. buttons is clicked.  The following paremeters are passed:
  82.  
  83.         message         WM_COMMAND
  84.  
  85.         wParam          Low Byte =  Toolbar ID
  86.                         High Byte = Toolbar button ID
  87.  
  88.         lParam          Low Word =  Toolbar button window handle
  89.                         High Word = BN_CLICKED
  90.  
  91. REMEMBER that even other child controls that you define (such as list boxes)
  92. will return with wParam = (Child ID << 8) | (Toolbar ID).  This means that
  93. you are restricted to having 256 toolbars and 256 toolbar buttons and child
  94. controls on each toolbar.  Well, life is tough, isn't it?
  95.  
  96. You enable and disable toolbar buttons by calling EnableToolbarButton
  97. with the following parameters:
  98.  
  99.         void EnableToolbarButton (HWND hwnd, int child, BOOL on)
  100.  
  101.         HWND hwnd           /* The window handle of the TOOLBAR */
  102.         int child           /* The ID of the toolbar button */
  103.         BOOL on             /* TRUE = Enable, FALSE = Disable */
  104.  
  105. You can also set or query the state of a toolbar button by sending the
  106. TOOLBAR BUTTON a BM_GETSTATE or BM_SETSTATE message, just as you would for
  107. a normal push button.  You can also send the BM_GETSTATE and BM_SETSTATE
  108. messages to the TOOLBAR, with the toolbar button's ID passed to lParam.
  109.  
  110. If, for some twisted reason, you want to modify the characteristics
  111. of the toolbar button dynamically, you can first call GetToolbarButton
  112. to fill in a TOOLBARICON structure:
  113.  
  114.         HWND GetToolbarButton (HWND hwnd, int child, TOOLBARICON *icon)
  115.  
  116.         HWND hwnd           /* The window handle of the TOOLBAR */
  117.         int child           /* The ID of the toolbar button */
  118.         TOOLBARICON *icon   /* Pointer to a TOOLBARICON structure.  If not
  119.                                NULL, the fields will be filled in with
  120.                                the most current settings. */
  121.  
  122. This routine will return the window handle of the toolbar button.  Now
  123. you can change the settings and then call ModifyToolbarButton:
  124.  
  125.         void ModifyToolbarButton (HWND hwnd, TOOLBARICON *icon)
  126.  
  127.         HWND hwnd           /* The window handle of the TOOLBAR BUTTON! */
  128.         TOOLBARICON *icon   /* The TOOLBARICON structure containing new
  129.                                settings */
  130.  
  131. There is also a neat little routine called Create3DEffect which will
  132. make any rectangle within any window look like a 3-dimensional bar:
  133.  
  134.         void Create3DEffect (HDC hdc, RECT *rect, int thickness)
  135.  
  136.         HDC hdc             /* Device context to draw on */
  137.         RECT *rect          /* Pointer to a RECT structure defining the
  138.                                area to make 3D.  If rect is NULL, then
  139.                                the entire window is 3D'd. */
  140.         int thickness       /* How thick you want the 3D effect to be */
  141.  
  142. If you want to change the name of the toolbar classes, they are defined
  143. in TOOLBAR.H
  144.  
  145. One final thing, you must remember to export ToolbarProc and
  146. ToolbarButtonProc in your .def file of course.
  147.  
  148.  
  149. Afterwords
  150. ----------
  151.  
  152. Theoretically, you are required to obtain special approval from me (because
  153. I copyrighted these routines) if you want to use them in your programs.
  154. However, I usually don't really care if you are not using these routines in
  155. a commercial, shareware etc. product.
  156.  
  157. Any questions and/or bug fixes, please send email to:
  158.  
  159.         Stephen Chung           stephenc@cunixf.cc.columbia.edu
  160.  
  161. If it bounces, then try schung@cogsci.Berkeley.EDU
  162.  
  163. Have fun!
  164.