GAB Code Editor v4 Alerts

From GAB Help
Jump to: navigation, search

< Back to main GAB Code Editor v4 Page

GABCE4 alert example.png

The new GAB Alert System allows a programmer to show the user popup messages, without blocking the UI thread. The programmer can specify several appearance parameters, and handle user interaction (clicks).

Getting Started

The Alert must have a related, visible form. Alerts will not show if the form is not visible.

  1. Create a new form, and save your project. Base Form and Dashboard Form are supported.
  2. In code, use the ShowAlert function on the form to show the alert. See the Functions section for details.

Functions

   Gui.Form..ShowAlert(AlertID As String, Caption As String, Text As String, [SvgImage As v.Enum.Image], [SvgWidth As Long], [SvgHeight As Long], 
       [Image As String], [autoCloseFormOnClick As Boolean], [ProgressMode As v.Enum.AlertProgressModes], 
       [ProgressMin As Long], [ProgressMax As Long], [ProgressValue As Long], [ShowPercentage As Boolean], [ProgressVisible As Boolean], 
       [DurationInMS As Long], [Pinned As Boolean])
   Gui.Form..UpdateAlert(AlertID As String, Caption As String, Text As String, [SvgImage As v.Enum.Image], [SvgWidth As Long], [SvgHeight As Long], 
       [Image As String], [autoCloseFormOnClick As Boolean], [ProgressMode As v.Enum.AlertProgressModes], 
       [ProgressMin As Long], [ProgressMax As Long], [ProgressValue As Long], [ShowPercentage As Boolean], [ProgressVisible As Boolean], 
       [DurationInMS As Long], [Pinned As Boolean])

ShowAlert and UpdateAlert are just multiple names for the same function. It will show an alert if the ID isn't already shown, or update the existing alert.

  • AlertID - (String) The unique ID of the alert. Can be reused once an alert is hidden.
  • Caption - (String) The title text on the alert.
  • Text - (String) The detail, clickable, text on the alert.
  • SvgImage - (v.Enum.Image) The SvgImage shown at the top left of the image, re-colored to work with the alert color.
  • SvgWidth - (Long, Default 24) The width of the SvgImage
  • SvgHeight - (Long, Default 24) The height of the SvgImage
  • Image - (String, Default Nothing) The non-Svg Image shown at the top left. Has a max size determined by the control. This is overridden by SvgImage.
  • AutoCloseFormOnClick - (Boolean, Default False)
  • ProgressMode - (v.Enum.AlertProgressModes)
  • ProgressMin - (Long) The minimum value on the progress bar
  • ProgressMax - (Long) The maximum value on the progress bar
  • ProgressValue - (Long) The current value on the progress bar
  • ShowPercentage - (Boolean, Default False) Sets if the percentage (46%, etc) is shown on the bar.
  • ProgressVisible - (Boolean, Default True) Sets if the progress bar is visible or not.
  • DurationInMS - (Long, Default 5000) Sets the length of time the alert is shown for, if not pinned.
  • Pinned - (Boolean, Default False) Sets if the alert is pinned, and will not close automatically.
   Gui.Form..UpdateAlertProperty(AlertID As String, PropertyName1 As v.Enum.AlertPropertyNames, PropertyValue1 As Object, ..., 
       PropertyNameN As v.Enum.AlertPropertyNames, PropertyValueN As Object)

The main function to update currently shown alerts. Allows the programmer to update one or more properties at the same time, without needing to specify all values.

  • AlertID - (String) The ID of the opened alert to update.
  • PropertyName1 - (v.Enum.AlertPropertyNames) - The name of the first property to update
  • PropertyValue1 - (Object) - The new value of the property named in PropertyName1
...
  • PropertyNameN - (v.Enum.AlertPropertyNames) - The names of the additional properties to update (alternating with values).
  • PropertyValueN - (Object) - The new value of the last PropertyName (alternating with names).

Events

  • Click - Raised when the user clicks the text on the alert. Includes arguments for ALERTID and ALERTTEXT.

Example

Here's an example of creating, and updating an alert

   Program.Sub.Main.Start
       Function.Intrinsic.UI.UsePixels ' Allows you to use Pixels instead of Twips throughout
       v.Local.i.Declare(Long)
       
       Gui.Form..Show
       
       ' Shows an alert with a caption, text property, and SvgImage
       Gui.Form..ShowAlert("myAlert","Caption","Put some of that sweet, sweet alert text here.",v.Enum.Image!BUG_BLACK)
       ' Sets the new alert to not auto-close
       Gui.Form..UpdateAlertProperty("myAlert","Pinned",True)
       ' Updates the caption, progress mode, and SvgImage of the alert        
       Gui.Form..UpdateAlertProperty("myAlert", v.Enum.AlertPropertyNames!Caption, "New  Caption", 
           v.Enum.AlertPropertyNames!ProgressMode, v.Enum.AlertProgressModes!Marquee,
           v.Enum.AlertPropertyNames!SvgImage,v.Enum.Image!ATTACH_BLACK)
       
       Function.Intrinsic.UI.SleepMS(2000) ' Wait to allow the Marquee to scroll
       
       ' Sets up progress bar to show values
       Gui.Form..UpdateAlertProperty("myAlert", v.Enum.AlertPropertyNames!ProgressMode, v.Enum.AlertProgressModes!Progress, 
           v.Enum.AlertPropertyNames!Min, 0, v.Enum.AlertPropertyNames!Max, 100)
       
       ' Loops 0-100, and increments the progress bar.
       F.Intrinsic.Control.For(v.Local.i,0,100,1)
           Gui.Form..UpdateAlertProperty("myAlert",v.Enum.AlertPropertyNames!Value,v.Local.i)
           Function.Intrinsic.UI.SleepMS(50)
       F.Intrinsic.Control.Next(v.Local.i)
       
       ' Closes the alert
       Gui.Form..HideAlert("myAlert")
   Program.Sub.Main.End
   
   Program.Sub.Form_AlertClick.Start
       ' Handles the user clicking the alert, and opens a MsgBox with title "You Clicked", and text "myAlert"
       Function.Intrinsic.UI.Msgbox(v.Args.ALERTID,"You Clicked")
   Program.Sub.Form_AlertClick.End