home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / PROG_BAS / TBAR15.ZIP / READ.ME < prev    next >
Text File  |  1994-01-15  |  17KB  |  437 lines
  1. ***************************************************************************
  2. *
  3. *  McKean Consulting
  4. *  Robin W. McKean
  5. *  1042 Braddock Circle
  6. *  Woodstock GA  30188
  7. *
  8. *  TBAR.VBX    V1.50.0000
  9. *
  10. *  Toolbar Custom Control for Visual Basic 3.0
  11. *
  12. ***************************************************************************
  13.  
  14. TBAR is a custom control for implementing industry standard toolbars in
  15. Visual Basic.  TBAR uses one bitmap, created by the developer, to display
  16. all buttons, in all button states.  One bitmap means faster loading and
  17. fewer system resources.  Additionally, you can design, define, and
  18. implement the behavior of your toolbar without writing a single line of
  19. code!  No longer do you have to be envious of Visual C++ or write your
  20. own code to implement toolbars.  TBAR will do everything for you.  Here
  21. are some features:
  22.  
  23.     * One bitmap defines all buttons, and all button states
  24.  
  25.     * All standard button types allowed, push, toggle, disabled, enabled
  26.  
  27.     * Group buttons.  When one is toggled, the others become untoggled
  28.  
  29.     * And more
  30.  
  31. ***************************************************************************
  32.  
  33. This ZIP file contains:
  34.  
  35.     TBAR.VBX         VB version of the TBAR custom control
  36.     PROJECT1.MAK    Sample project file for TBAR
  37.     MDIFORM1.FRM    Sample MDI form with toolbar
  38.     MDIFORM1.FRX    File used by VB for MDIFORM1
  39.     FORM1.FRM        Form with some simple information
  40.     READ.ME            This file
  41.     TOOLBAR.BMP        Bitmap of toolbar utilized by the sample
  42.  
  43. ***************************************************************************
  44.  
  45. REGISTRATION
  46.  
  47. If you like and appreciate this custom control...
  48.  
  49.   1)  Small time developers like me, send $20.00 to the address listed above
  50.   2)  Corporate users send $25.00 to the address listed above
  51.   3)  Register in the CompuServe SWREG Forum ID 1700 for $15.00
  52.  
  53. Registered users may purchase the source...
  54.  
  55.   Send $35.00 to me at the above address.
  56.  
  57.   This control is written in C++ and has been compiled using both
  58.   Borland C++ 3.1 and Visual C++ 1.0.
  59.  
  60. You may now register this control in the SWREG on Compuserve.  Type GO SWREG.
  61. If you want the source, you will still have to write me...
  62.  
  63. Corporate users should register via mail.
  64.  
  65. ***************************************************************************
  66.  
  67. WARRANTY
  68.  
  69. The control, as is, works the way that I want it to.  This does not mean
  70. that it will work the way that you want it to.   Along those lines, I
  71. totally disclaim that the control will do anything whatsoever.  This
  72. includes any implied abilities and any WARRANTIES, including those for
  73. SUITABILITY for a particular purpose, MERCHANTIBILITY, and all that other
  74. bull crap.
  75.  
  76. ***************************************************************************
  77.  
  78. PROGRAMMER'S NOTES (or, what I need to know to use this custom control)
  79.  
  80. The properties for this control can be broken down into two areas.  The
  81. first are properties which apply to the whole toolbar, and properties
  82. which apply to individual buttons.  Individual button properties will
  83. change as you change the currentButton property, or, as you select a
  84. button on the screen, during design, with the right mouse button.
  85.  
  86. The final section will cover the events provided by the Toolbar.
  87.  
  88.  
  89. TOOLBAR PROPERTIES
  90.  
  91. Outline
  92.  
  93. This property determines whether or not their is a solid line separating
  94. the toolbar from its parent window.  Most standard toolbars have a solid
  95. line of some sort to emphasize the toolbar.  When the toolbar is aligned
  96. top, then there is a line at the bottom.  When the toolbar is aligned
  97. bottom, there is a line at the top.  When there is no alignment, than
  98. this property draws a border around the toolbar.
  99.  
  100. OutlineColor
  101.  
  102. This is the color of the toolbar outline.  It's default is black.
  103.  
  104. Interval
  105.  
  106. This property represents the amount of space, in pixels, between the
  107. buttons in the toolbar.  If you want all buttons to have a little
  108. space between them, set this property to 2.  If you want more distinct
  109. button borders, set this property to one.  The demo has this property
  110. set to 0.
  111.  
  112. ButtonWidth
  113.  
  114. This property tells TBAR how wide, in pixels, each button is in your BITMAP.
  115. TBAR will add 8 pixels to this value to determine the true button size.  As
  116. you design your bitmap for your toolbar, you should decide beforehand what
  117. each button bitmap size will be.  The demo bitmap is 16 pixels wide by 15
  118. pixels high.  There are ten buttons, so the bitmap is 160 pixels wide.  Some
  119. resource editors allow you to break up your bitmap into grids, some don't.
  120. You could use PaintBrush to edit your bitmaps.
  121.  
  122. ButtonHeight
  123.  
  124. This property tells TBAR how high each bitmap is.  This property is used, and
  125. may be used later to divide bitmaps horizontally as well as vertically.  The
  126. bitmap provided with the demo is 15 pixels high.
  127.  
  128. Bitmap
  129.  
  130. This is the property for the bitmap which represents the buttons on your toolbar.
  131. There are some important things for you to remember when designing your bitmap.
  132. All important areas of your bitmap should be outlined in black.  The black areas
  133. will be greyed when the bitmap is disabled.  The normal background color,
  134. RGB(128,128,128) (LTGRAY), must only be used for the background.  This color is
  135. masked out when re-drawing the button as pressed, toggled, and disabled.  You
  136. may not use another background color.  This is consistent with most toolbars
  137. currently in the industry.  The demo uses black and white as the only colors.
  138. Microsoft (TM) uses these colors in all of their applications.  You, however, may
  139. use other colors if it suits your purpose.  The only restrictions are those
  140. mentioned above.
  141.  
  142. VisibileButtons (Yea, I spelled it wrong, duh???)
  143.  
  144. This is the number of buttons visible on the screen.  It is possible to change the
  145. number of visible buttons at run-time to un-hide buttons at the end of the toolbar.
  146. I must warn you.  This feature is not tested.  I have plans in the works to allow
  147. drag and drop of buttons on the toolbar.  At that time, this feature will become
  148. more stable.  For right now, it might be best to only set this property at design
  149. time.  (But key, try it if you want.)
  150.  
  151. LeadingInterval
  152.  
  153. This property is the number of pixels between the beginning of the toolbar and the
  154. first button on the toolbar.
  155.  
  156. CurrentButton
  157.  
  158. For setting button properties, this property determines which button will be affected.
  159. When you select a button with the right mouse button during design, this property will
  160. be set for you.
  161.  
  162.     TBar1.CurrentButton = 0
  163.     TBar1.Gap = "5"
  164.  
  165. ButtonState
  166.  
  167. This property is not available at design time.  You can change the enabled/disabled or
  168. toggled/untoggled state of a button by using this property.  The following values are
  169. hard coded by the system:
  170.  
  171.     BS_IS_TOGGLED                    1
  172.     BS_IS_ENABLED                    2
  173.     BS_IS_NOTTOGGLED                3
  174.     BS_IS_NOTENABLED                4
  175.     BS_IS_VISIBLE                    5
  176.     BS_IS_NOTVISIBLE                6
  177.  
  178. So, if I wanted to disable the second button (0 index) on the bitmap, I might do something
  179. like this:
  180.  
  181.     TBar1.ButtonState(2) = 4
  182.  
  183. Since the states of the button are indeterminite, reading this property will not return
  184. anything meaningful.  Additionally, in version 1.5, the index member of this property
  185. now corresponds to the ID of the bitmap, not the logical index of the bitmap.  This allows
  186. the developer to change the button state of any button, no matter where it has been
  187. moved to by the user (if you are using AutoPlacement feature).  These new enhancements
  188. are fully compatible with previous versions.
  189.  
  190. RoundedCorners
  191.  
  192. Setting this propery to True will cause the edges of all buttos to appear somewhat rounded.
  193.  
  194. Id
  195.  
  196. This property sets and gets the id of the the button at the requested index.  This property
  197. allows you to set the bitmap of any button on the toolbar to any section of the bitmap your
  198. toolbar is using.  For example:
  199.  
  200.     You bitmap is 100 wide by 50 deep.  Each bitmap you are using for a button is 25 pixels
  201.     wide (ButtonWidth) and 25 pixels high (ButtonHeight).  So, the bitmap is divided into
  202.     4x2 bitmaps.  To set the first button in your toolbar to the first bitmap on the
  203.     second row, you can say:
  204.  
  205.         TBar1.Id(0) = 4
  206.  
  207.     Then, you can disable that same button by doing:
  208.  
  209.         TBar1.ButtonState(4) = 4    ' ButtonState uses Id for reference
  210.  
  211. You may use this property to get the Id(s) of each button in the toolbar as well.
  212.  
  213. AutoPlacement
  214.  
  215. Setting this property to True will allow the end user to drag and drop buttons on the
  216. toolbar to new places using the right mouse button.  Try this one out and see if it
  217. fits into your application.  You can save the placement using the IdList property and
  218. then restore the button order by setting this property when the application is
  219. started.  (See IdList.)
  220.  
  221. IdList
  222.  
  223. This property returns a string of Ids for each button in the bitmap.  You can then use
  224. this string later to restore the order of the buttons when the user restarts the
  225. program, or you can use it to set and show different sets of buttons in the toolbar.
  226. For example:
  227.  
  228.     ' Restore previous button state
  229.     Dim A$ As String * 81
  230.     GetPrivateProfileString("Toolbar","ButtonOrder","0;1;2;3;4;5;6;7;8;9",A$,80,"TOOLBAR.INI")
  231.     TBar1.IdList = A$
  232.  
  233. Now, say when the user pops up a certain document in an MDI application, you want to show
  234. four buttons which do a certain set of operations:
  235.  
  236.     Command1_Click()
  237.         TBar1.VisibileButtons = 4                ' Number of buttons on bar
  238.         TBar1.IdList = "12;13;14;15"            ' Each buttons Id
  239.     End Sub
  240.  
  241. BevelWidth
  242.  
  243. This property controls the width of the white and dark grey lines around the outside
  244. of the button.  Changing this property will enhance or reduce the 3D effects of the
  245. button.  Valid bevel widths are between 1 and 10.
  246.  
  247. PressedBevelWidth
  248.  
  249. This property controls the width of the black lines around the outside of the button
  250. when it is pressed.  Changing this property will enhance or reduce the 3D effects of the
  251. button.  Valid pressed bevel widths are between 1 and 10.  This value should always be
  252. less than or equal to the BevelWidth property.
  253.  
  254. TOOLBAR BUTTON PROPERTIES
  255.  
  256. Toolbar button properties are stored as strings.  So, you should always set these
  257. properties using strings.
  258.  
  259. Gap
  260.  
  261. This property represents the gap between CurrentButton and the next button.  This property
  262. is stored in Pixels.  The demo program uses this value to put spaces in between buttons
  263. in groups or which have similar purposes.
  264.  
  265.     TBar1.Gap = "10"        ' Put 10 pixesl between CurrentButton and the next
  266.  
  267. This property is mostly set at design time.  But you can set it at run time.
  268.  
  269. Sticky
  270.  
  271. This property determines whether or not the button can be "toggled".  Setting this
  272. property to "1" allows this button to remain pressed when the mouse is released, and
  273. then to be unpressed, when pressed with the mouse again.  Buttons with this property
  274. set to "1" will respond to the Toggle event.
  275.  
  276.     TBar1.CurrentButton = 1
  277.     TBar1.Sticky = "1"
  278.  
  279.     TBar1.CurrentButton = 1
  280.     TBar1.Sticky = "0"            ' Button is not sticky
  281.  
  282. Disabled
  283.  
  284. This property determines whether or not the button can be pressed with the mouse.
  285. Setting this property to "1" disables all "Click" events for that button.  Normal
  286. buttons on the toolbar provide a Click event when the mouse button is pressed then
  287. released on them.  In addition, the button will appear as "greyed" on the screen.
  288.  
  289.     TBar1.CurrentButton = 5
  290.     TBar1.Disabled = "1"
  291.  
  292.     TBar1.CurrentButton = 5
  293.     TBar1.CurrentButton = "0"    ' Renable button
  294. Group
  295.  
  296. This property should only be used by "Sticky" buttons.  Sticky buttons can be grouped,
  297. so pressing one sticky button causes all other sticky buttons in the group to become
  298. unpressed.  You can enter the index of any other sticky buttons in the group
  299. separated by a comma.  This property should be set at design time, but you can read
  300. from and write to it at run time.  It is a string property as well.
  301.  
  302.     TBar1.CurrentButton = 8            ' Set the current button
  303.     TBar1.Group = "7,9"                ' Set the other buttons in his group
  304.  
  305. To disable the group set Group = "None"
  306.  
  307.     Tbar1.CurrentButton = 3
  308.     TBar1.Group = "None"
  309.  
  310.  
  311. ButtonVisible
  312.  
  313. This property defaults to True.  Setting it to False causes that button to be invisible.
  314. Note that the button that is affected is the controlled by the CurrentButton property.
  315. Note additionally, that the CurrentButton property is a logical index into the button
  316. array.  Along those lines, this property should really only be used at design time.
  317. Use the ButtonState property to hide and unhide buttons by ID during run time.
  318.  
  319. TOOLBAR EVENTS
  320.  
  321. Click
  322.  
  323. This event is called when the user presses a "normal" button, and then releases the
  324. mouse over the button.  The parameter "Button", passed to this event, tells the
  325. developer which button was pressed.  Note that this parameter is now the button's id,
  326. in case AutoPlacement is turned on, clicking the same button, no matter where it has
  327. been moved, will cause the same Click command to be generated.
  328.  
  329.     TBar1_Click(Button As Integer)
  330.  
  331.         ' When save file is pressed, save the file, then disable the button until
  332.         ' the current document is dirty again.
  333.         Select Case    Button
  334.             Case 0:
  335.                 NewDocument
  336.             Case 1:
  337.                 OpenDocument
  338.             Case 2:
  339.                 SaveToFile
  340.                 TBar1.ButtonState(Button) = 4
  341.         End Select
  342.     End Sub
  343.  
  344. Toggle
  345.  
  346. This event is called when the state of a "Sticky" button changes.  If the sticky
  347. button is part of a group, then this event will be called twice, once for the button
  348. getting pressed, and once for the other button in the group which will be unpressed
  349. when the current button does down.
  350.  
  351.     TBar1_Toggle(Button As Intger, State As Integer)
  352.  
  353.         Select Case Button
  354.             Case 7:
  355.                 SetAligment LeftJustify,State
  356.             case 8:
  357.                 SetAlignment RightJustify,State
  358.             Case 9:
  359.                 SetAlignment CenterJustify,State
  360.         End Select
  361.  
  362.     End Sub
  363.  
  364. DoubleClick
  365.  
  366. This event is called when the user double clicks a button.  I'm not sure
  367. what this will be used for, but it is provided in case a user has
  368. special needs.
  369.  
  370. MouseDown
  371. MouseMove
  372. MouseUp
  373.  
  374. These events are called when a mouse action has taken place upon the
  375. toolbar.  Each one of these events take the following parameters:
  376.  
  377.     TBar1_MouseDown(MouseButton As Integer, Shift As Integer, X As Single,
  378.                         Y As Single, Button As Integer)
  379.     TBar1_MouseMove(MouseButton As Integer, Shift As Integer, X As Single,
  380.                         Y As Single, Button As Integer)
  381.     TBar1_MouseUp(MouseButton As Integer, Shift As Integer, X As Single,
  382.                         Y As Single, Button As Integer)
  383.  
  384. MouseButton indicates which mouse button caused the event.  This parameter
  385. is equivelent to the Button parameter for normal MouseDown events, as in
  386. the VB Help File.  This parameter is 1 for the left button, 2 for the right
  387. button, and 4 for the middle button.
  388.  
  389. Shift represents the state of the Ctrl and Shift keys.  I did not include
  390. the Alt key.  I didn't see the purpose for this, and the Alt key state is
  391. not provided as a default in the mouse event.  I will include the Alt key
  392. state if any requests me to do so.  The shift states are 1 for Shift down,
  393. and 2 for Control button down.
  394.  
  395. X is the location on the screen, in twips of the mouse events x location.
  396.  
  397. Y is the location on the screen, in twips of the mouse events y location.
  398.  
  399. Button is the toolbar button, over which, the current mouse event took
  400. place.  If there was no button under the mouse event, then this parameter
  401. will be equal to negative 1.
  402.  
  403. ***************************************************************************
  404.  
  405. REACHING THE AUTHOR
  406.  
  407. I can be reached via U.S. Mail at the address listed above.  You can reach
  408. me via E-Mail at the following locations...
  409.  
  410. CompuServe:            Robin W. McKean
  411.                     72622,1403
  412.  
  413. Shareware South:    (404) 370-0872
  414.                     Robin W. McKean
  415.                     Atlanta, GA
  416.  
  417. I'm on CompuServe once or twice a day.  I check Shareware South about once
  418. a week.
  419.  
  420. ***************************************************************************
  421.  
  422. REVISION HISTORY
  423.  
  424. 1.00.0000    Initial release of the TBAR.VBX Custom Control
  425. 1.50.0000    Added properties for visible buttons, ids, bevels,
  426.         autoplacement, rounded corners, and improved the
  427.         look of disabled bitmaps.
  428. 1.51.0000    Fixed bug when loading a form saved as text
  429.  
  430. ***************************************************************************
  431.  
  432. ACKNOWLEDGEMENTS
  433.  
  434. Thanks to James Moore for the bug report on Forms saved as text.
  435.  
  436. ***************************************************************************
  437.