BetterButtons v0.1.3 formerly Canvas2Buttons

[Julian]

Hi,

Having recently started developing a cross platform app in Purebasic (coming "soon") I found the need for a robust, easy to use and feature rich cross platform button control.



There's two main ways to use this library. You can either code the buttons yourself (see Example.pb), or you can use the form designer with ButtonImage's (see Example Form.pb and Example Form.pbf). The library will replace all ButtonImage's on a form with a BetterButton so no additional programming will be needed if you don't want to.

States

There is a very simple system of adding additional states using the ToolTip text. Sates are entered as a comma separated list surrounded by [[ ]]. Each button has a default "up" state and can have any combination of the following states:

• down - used for a toggle state, when the button is down (checked)
• up_hover - shown when the mouse if over the up (unchecked) state button
• down_hover - shown when the mouse is over the down (checked) state button
• up_disabled - shown when the button is disabled in its up (unchecked) state
• down_disabled - shown then the button is disabled in its down (checked) state

The following will allow keyboard input (enter/space) to trigger the button which had focus

• focus - enables button to retain focus, uses hover state as focus
• focusno - enables button to retain focus, does NOT use hover state as focus so you can create a custom focus using callbacks

You can also enter debug if you want to debug a button.

These states can be added at form design time by entering a comma separated list into the ToolTip of a button surrounded by [[ ]] at any position in the Tooltip. For example:

• [[down]]Tooltip goes here
• [[up_hover,down_hover]]Tooltip goes here
• Tooltip goes here[[focus,down,up_disabled,down_disabled]]

If you wish to use the simple method of adding buttons by using Tooltip text, your images will need to follow a certain naming format which is the name of the image e.g. plus followed by an _ then the state and finally the extension. For example having a button named plus would need the following images if all states were in use:

• plus_up.png
  plus_down.png
  plus_up_hover.png
  plus_down_hover.png
  plus_up_disabled.png
  plus_down_disabled.png

Callbacks

Callbacks can now be entered at design time using the form editor. This is done in a similar way to the states above using the tooltips of the buttons. Callback procedures and events are separated by a comma, and events are separated using vertical pipes |. There can be only one callback procedure per set (( )). However you can add multiple callbacks for the same event by creating another set ((NameOfCallbackProcedure,Event1))

To add a callback use the following format:

((NameOfCallbackProcedure,Event1|Event2|Event3|...))

For example:

• ((ButtonClick,#B8_Event_ButtonPressed))
  This will call ButtonClick when the button is pressed
• ((ButtonClick,#B8_Event_ButtonPressed))((ButtonCallbackFocus,#B8_Event_DrawFocusFront|#B8_Event_DrawFocusBack))
  This will call ButtonClick when the button is pressed and ButtonCallbackFocus when we want to render the front and back of the button for special button effects
• ((ButtonClick,#B8_Event_ButtonPressed))((ButtonImage_11Callback,#B8_Event_Draw|#B8_Event_ButtonPressed))
  This will call ButtonClick when the button is pressed and ButtonImage_11Callback when we want to render the button or the button is pressed

When declaring the callback procedure in your code for callbacks created via Tooltips, you will need to use the following format:

Code: Select all

Runtime Procedure CallbackProcedureName(event)
  Protected *button.B8_Button = B8_GetEventButton() ; find out which button caused the callback, this can be left out if you have one callback per button
EndProcedure

If you create the callbacks in code by hand (not using Tooltips) , then you can leave out the "Runtime" declaration.
Cutom events include:

• #B8_Event_LeftButtonUp
  #B8_Event_LeftButtonDown
  #B8_Event_ButtonPressed
  #B8_Event_Draw
  #B8_Event_DrawBack
  #B8_Event_DrawFocusBack
  #B8_Event_DrawFront
  #B8_Event_DrawFocusFront
  #B8_Event_KeyUp
  #B8_Event_KeyDown
  #B8_Event_MouseEnter
  #B8_Event_MouseLeave
  #B8_Event_Focus
  #B8_Event_LostFocus

Features

• Cross platform
• 6 states, up, down, up (mouse over), down (mouse over), up disabled and down disabled
• Callbacks, no need to clutter up your main loop
• Replace those radio buttons, push buttons and toggle buttons
• State management inside the button with direct access via Get/Set to find out what the button is doing
• Focus tracking (tab and shift+tab enabled)
• Simulated transparency of the canvas button so you can have graduated backgrounds on your forms
• Correct state management for situations such as mouse down, drag off then back on button

Callbacks

• Callbacks for multiple render layers, so you can draw in-front / behind the button, want a button with a counter on it? No problem!
• Custom focus callbacks so you can draw the focus how you like
• Callback to replace the main draw routine if you want to perform some custom button rendering
• Dont like making multiple images for your states, one simple callback for an XOR'd button

Download v0.1.3 source with examples

This library also ships with my new ImageLibrary which I needed to code to allow certain features in BetterButtons. See ImageLibrary.pb for more information (link to follow).

I'm open to constructive comments on coding style, ease of use and feature requests. If you find any bugs/problems or have any questions please post them here. I'm currently testing this on Windows 8.1 and the latest OSX, feedback from other platforms would be much appreciated. The example app might have some funky formatting on other platforms, it was just done to show the features and how to achieve them.

I hope you find it useful.

Regards,

Julian

Version History
28/04/15 - v0.1.0

• Initial release

29/04/15 - v0.1.1

• Bug fixes + AddImages()

30/05/15 - v0.1.2

• Purebaseic Form compatability added, automatically change ButtonImage to Canvas
• [[down,up_hover,down_hover,up_disabled,down_disabled]] can now be added to ToolTip to set up states
• ((NameOfCallbackProcedure,Event1|Event2|Event3)) can now be added to ToolTip for custom callbacks
• GetGadgetDisabled(Gadget) returns #True / #False if the gadget is currentl disabled
• SetGadgetState can be used to set button state, 3rd parameter added to trigger callback on #True / #False
• GetGadgetState(Gadget) returns checked status of button #True / #False
• Uses new ImageLibrary
• Overloaded the following procedures to allow seamless integration:
  ButtonImageGadget
  CloseWindow
  DisableGadget
  FreeGadget
  GadgetToolTip
  GetGadgetDisabled
  GetGadgetState
  OpenWindow
  SetGadgetState (additional optional parameter, triggerCallback #True/#False)

26/06/15 - v0.1.3

• Added GetGadgetTooltip(canvas) - Returns a string containing the Tooltip of the BetterButton
• Added GetGadgetTooltipRaw(canvas) - Returns a string containing the raw Tooltip data of the BetterButton (includes bracketed data)
• Added more events for callbacks:
  #B8_Event_MouseEnter (see button 2 for example)
  #B8_Event_MouseLeave (see button 2 for example)
  #B8_Event_Focus
  #B8_Event_LostFocus
• Bug fixes:
  When debugging is enabled via Tooltips (was incorrectly enabling focus)
  Fixed error when trying to set a tooltip of a non-BetterButton

[Julian]

Examples

There are 12 example buttons included in the download which show off all the features of BetterButtons, here's a few animated examples of what can be achieved with just a couple of lines of code.



Use the form designer and enter the following in the button's ToolTip:

Code: Select all

Button 3[[up_hover,down_hover]]((ButtonClick,#B8_Event_ButtonPressed))

or code it yourself:

Code: Select all

button3 = CanvasGadget(#PB_Any, 10, 90, 20, 20)

B8_CreateButton(button3, frmExample, up)
B8_AddImages(button3, #Null, up_hover, down_hover) ; Null is the down state which means this is just a push button

B8_RegisterCallback(button3, @ButtonCallback(), #B8_Event_ButtonPressed)

Use the form designer and enter the following in the button's ToolTip:

Code: Select all

Button 5[[down, up_hover,down_hover]]

or code it yourself:

Code: Select all

button5 = CanvasGadget(#PB_Any, 10, 170, 20, 20)
text5 = TextGadget(#PB_Any, 50, 175, 300, 20, "Button 5 - hover, down, checked no event")

B8_CreateButton(button5, frmExample, up)
B8_AddImages(button5, down, up_hover, down_hover) ; No Null here, this is now a toggle button which latches in the up and down positions

[Julian]

[Reserved for FAQ]

[infratec]

Hi,

just tested and ...

I got an IMA at the end of ButtonCallbackCounter().
Also with enabled Purifier I got no better fault description.

Win7 PB 5.31 x86

And my first impression: a bit complicated.

Bernd

[Julian]

Hi Bernd,

Thanks for testing, I didn't even think that 32bit would cause problems over 64bit that I'm running on. I'll add that into my tests next time.

I found the problem, some callbacks were using the wrong number of parameters and only caused problem in 32bit, these have been fixed.

I have also taken your first impression comment onboard that its a little complicated and I have added the following:

Code: Select all

C2B::AddImages(button9, down, up_hover, down_hover, up_disabled, down_disabled)

This call alone will save 5 lines of code adding images for each event. If you want to ignore an addition for a certain event, simply use #Null (0) in place of a #Image

I have updated the link to the new version 0.1.1

Regards,

Julian

[Julian]

Name change to reflect additional functionality.

Major update:

You can now have a fully functional button with one line of code, everything else can be automatically generated using the ToolTips of buttons in the form designer.

Code: Select all

XIncludeFile "BetterButtons.pbi"

15/05/15 - v0.1.2

• Purebaseic Form compatability added, automatically change ButtonImage to Canvas
  [[down,up_hover,down_hover,up_disabled,down_disabled]] can now be added to ToolTip to set up states
  ((NameOfCallbackProcedure,Callback1|Callback2|Callback3)) can now be added to ToolTip for custom callbacks
  GetGadgetDisabled(Gadget) returns #True / #False if the gadget is currentl disabled
  SetGadgetState can be used to set button state, 3rd parameter added to trigger callback on #True / #False
  GetGadgetState(Gadget) returns checked status of button #True / #False
  Uses new ImageLibrary
  Overloaded the following procedures to allow seamless integration:
  ButtonImageGadget
  CloseWindow
  DisableGadget
  FreeGadget
  GadgetToolTip
  GetGadgetDisabled
  GetGadgetState
  OpenWindow
  SetGadgetState (additional optional parameter, triggerCallback #True/#False)

[juror]

Useful.

Thanks for sharing with us.

[Tenaja]

The zip file link goes 404.

[ts-soft]

The zip file link goes 404.

With rightclick you can download, but the archive seems broken!

[Julian]

The zip file link goes 404.

Oops fixed!

[ts-soft]

You have to change Example.pb to:

Code: Select all

;-load images
Define up = LoadImage(#PB_Any, "icons/plus_up.png", 0, #True)
Define down = LoadImage(#PB_Any, "icons/plus_down.png", 0, #True)

Define up_hover = LoadImage(#PB_Any, "icons/plus_up_hover.png", 0, #True)
Define down_hover = LoadImage(#PB_Any, "icons/plus_down_hover.png", 0, #True)

Define up_disabled = LoadImage(#PB_Any, "icons/plus_up_disabled.png", 0, #True)
Define down_disabled = LoadImage(#PB_Any, "icons/plus_down_disabled.png", 0, #True)

So it should work on linux and windows.
Some changes for the second example required, but i haven't time to solve this.

Greetings - Thomas

[Julian]

Made a couple of bug fixes to the examples that didn't need an updated version number, just grab the new zip.

[ts-soft]

Run fine on linux!

[Kwai chang caine]

Works fine
Thanks for sharing

[Julian]

Updated version:

26/06/15 - v0.1.3

• Added GetGadgetTooltip(canvas) - Returns a string containing the Tooltip of the BetterButton
• Added GetGadgetTooltipRaw(canvas) - Returns a string containing the raw Tooltip data of the BetterButton (includes bracketed data)
• Added more events for callbacks:
  #B8_Event_MouseEnter (see button 2 for example)
  #B8_Event_MouseLeave (see button 2 for example)
  #B8_Event_Focus
  #B8_Event_LostFocus
• Bug fixes:
  When debugging is enabled via Tooltips (was incorrectly enabling focus)
  Fixed error when trying to set a tooltip of a non-BetterButton