User Tools

Site Tools


axcontrolgrid

AXControlGrid

AXControlGrid is a complete and powerful Xojo desktop UI component for macOS and Windows that it makes possible to put Canvas-based controls in a Page or a series of Pages of a given size (width and height).

It allows for the additional displaying and layout of associated text captions, and the rendering of such page content as Pictures objects so you can do further operations on them: including saving them to a database or as files, generating PDF files, sending them via email, printing them, etc.

From the developer point of view everything is configurable and every change is visible on the fly, including the re-layout of the Page Contents to reflect the new settings applied.

From the point of view of a final user, they will be able to Zoom the Page contents, navigate between the available pages, drag and drop new items to add them to the currently visible Page, select a range of items in the Page to cut and paste or delete them, besides writing and modifying caption texts (and their settings) or undoing every action done!

Among other operations, the base AXControlGrid component (BaseBoard) allows the following operations:

  • Set and change the main board (Page) size.
  • Set and change the Page items size.
  • Add new controls via code, or Drag and Drop.
  • Delete selected controls.
  • Cut and Paste (or move) selected controls; for example, rearranging a series of controls to a new position or Page.
  • Change Text Captions Font, text size, Alignment and the text caption box height to accommodate any needed amount of text.
  • Set and change text captions gutter.
  • Unlimited undo for every action done, including zoom levels, page changes, page frame position, control size or text caption changes, etc.

Minimum Requirements

AXControlGrid requires Xojo 2017r3 or later on macOS, and Xojo 2018r3 or later on Windows; both for generating 32 and 64 bit executables.

Note: The compatibility with Xojo 2019r2 is in the works. Stay tuned!

Supported Xojo Editions:

  • Xojo Desktop
  • Xojo Pro
  • Xojo Pro Plus

Both the AXControlGrid component and the provided Demo Project had been tested on the following Operating Systems versions:

  • macOS 10.12.6 (Sierra)
  • macOS 10.14.x (Mojave)
  • macOS 10.15.x (Catalina)
  • Windows 7
  • Windows 10

The demo project is fully functional and whithout limitations when run from the Xojo IDE, but you need a License in order to deploy (compile) a project that includes AXControlGrid.

AXControlGrid license users are entitled to receive for free all the component updates published for 12 months after purchase.

Licensing The Component

Call the License method on the BaseBoard class with the data received from AprendeXojo in order to license your copy of AXControlGrid:

BaseBoard.License(“Name”,“Surname”,“Data”)

Source Code

Feel free to contact me if you are interested in an edition with no encrypted components (access to the source code).

How to setup AXControlGrid in your projects

AXControlGrid includes a complete Xojo Demo Project that you can use and explore to learn about all the features and capacities. In addition, the Demo Project has lots of code comments for the methods and events under the MainWindow, wCaptions and wAXControlGridContent windows. Basically, showing you how to use the public API exposed by the BaseControl Container Control of the component.

Nevertheless, follow these steps if you need a fast path to setup AXControlGrid in a new project:

  1. Copy the AXControlGrid folder from the Demo Project.
  2. Paste it into a new Xojo Project.
  3. From the AXControlGrid folder in your project, drag the BaseBoard ContainerControl and place it at the desired position of a Window in the Layout Editor.
  4. Using the Xojo Layout Editor, set the width and height of the BaseBoard instance (named BaseBoard1 by default). Optionally, click on the position locks of the Inspector Panel so it keeps its top, bottom, left and right margins attached to the window margins when resized. AXControlGrid keeps its size changes in the Undo Stack.

AXControlGrid needs a RectControl acting as a Template for the items (controls) added to the BaseBoard (Page or Pages). Setting this kind of control in your project is very easy:

  1. Drag any Canvas based subclass of yours to the same Window where the BaseBoard1 instance has been added. If you don't have any Canvas based subclass at hand, you can use the AXImageCanvas UI component or the, more basic, MyCanvas also included in the demo project.
  2. In order for the Canvas based subclass to act as a control template, it needs to be configured as a Control Set using the Inspector Panel. This is the Xojo mechanism that allows the creation and use of new UI controls at runtime.
  3. For enabling a Canvas based control as a Control Set (or any other, for the case), select the instance added to the Window in order to access the Inspector Panel; then, click on the cog wheel icon on the Inspector Panel to access the Attributes section.
  4. Select the New Control Set option in the Member Of popup menu of the Control Set section.
  5. Click on the ID icon on the Inspector Panel to return to the main settings section, and disable the Visible property. This is mandatory so our control template would not be visible at runtime, and doesn't interfere with the UI of the App.

Now, with our BaseBoard1 instance and control template set, you will be able to add new items to the BaseBoard1 pages using a fragment of code like this (MyControlTemplate1 refers to the name of the Canvas based instance previously added to the Window):

Dim c As New MyControlTemplate1

Call BaseBoard1.AddControl c

Probably you'll find of interest the code for the pbAddControls Action Event in the Demo Project to learn how it is possible to add several kind of controls.

From this point on, I recommend to explore the Demo Project and start using the public Methods provided by the BaseBoard Container Control in order to use all its features.

AXControlGrid default settings

The main Board (or page) use these default values. You can always change them from code:

  • Page Size: 300 x 500 px
  • Control Size: 50 x 50 px
  • Gutter: 10 px
  • Caption Boxes Height: 50 px
  • Caption Boxes Gutter: 5 px
  • Caption Boxes text size: 10 pt
  • Caption Boxes Font: System default
  • Caption Boxes Alignment: Left

How final users interact with AXControlGrid

The final users of an app containing the AXControlGrid component will be able to do the following actions:

  • Zoom: click on the lower right “-” and “+” buttons or set a new Zoom value in the lower right text field. Press the Alt key (Ctrl on Windows) in combination with the mouse wheel or trackpad gesture.
  • Change Page: Click and change the value in the lower left text field. Use the left and right arrow cursor keys. Press the Alt key (Ctrl on Windows) in combination with the mouse wheel or horizontal trackpad gesture.
  • Select Items: Drag the mouse or trackpad cursor to draw a selection marquee around the items to be selected.
  • Copy / Move items: Use Command + C keyboard shortcut (Ctrl + C on Windows) to cut the selected Items. Press the Alt key (Shift key on Windows) while dragging the mouse to move the selected items to a new position in the Page.
  • Insertion Point: After a Cut or Move action, move the mouse cursor to the insertion point for the items available in the Clipboard. The insertion point is previewed with a vertical red line.

Undo Actions

AXControlGrid can Undo the following actions:

  • Adding new items.
  • Changes in the main Board (Page) Size.
  • Changes of the displayed Page.
  • Changes in Control Size.
  • Changes in the Gutter (margin) value.
  • Changes in the Captions boxes Height.
  • Changes in the Captions Gutter (upper margin) value.
  • Changes in the Captions Text size.
  • Changes in the Captions Font.
  • Changes in the Captions Alignment.
  • Cut.
  • Paste.
  • Applied Zoom levels.
  • Displayed Page Area (when the zoom level for the Page is greater than the available main Board area).

Localization

AXControlGrid includes the AXControlGridStrings Module with all the strings used in the component. By default, it includes the strings localized both in English and Spanish. You can edit them or add new language localizations at your will.

BaseBoard Container Control Methods

Method SignatureDescription
Public Function AddControl(byref ControlTemplate as RectControl) as BooleanAdds a new control instance to the main board (Page). The control passed as a reference must be configured as a Control Set in the app Window Layout. This Control Set acts like a template for the operation of this UI component and properties like the Width, Height, Visibility and others should be managed by the component itself, including closing (disposing) it when not is necessary anymore; for example, when the user (or via code) has decided to delete it from the Page.
Public Function CaptionForControl(c as RectControl) as CaptionTextAreaReturns the Text Caption control associated with the RectControl received as parameter. The Caption UI control is a subclass of TextArea. Properties like Height, Width, Visibility, TextSize, TextFont, Alignment (and SelAlignment) should be left managed exclusively via the AXControlGrid component.
Public Sub CaptionGutter(Size as integer)Set the Gutter (upper margin) used for the layout of the Text Caption boxes to the new value. This value is applied to all Caption Boxes.
Public Sub CaptionHeight(size as integer)Set the Text Caption height to the new value. This value is applied to all Caption Boxes.
Public Sub CaptionsAlign(Alignment as integer)Set the Text Caption alignment to the new value. This value is applied to all Caption Boxes.
Public Sub CaptionsEnabled(Enabled_Value as Boolean)Enables/Disables the visibility state for the Text Caption Boxes.
Public Sub CaptionsFont(FontValue as String)Set the Text Caption Font to the new value. This value is applied to all Caption Boxes.
Public Sub CaptionsTextSize(Size as integer)Set the Text Caption text size to the new value. This value is applied to all Caption Boxes.
Public Sub ClearPasteboard()Deletes the Paste status of the AXControlGrid Pasteboard. Useful, for example, when you don't want to keep the reference to the previously cut Controls (so they couldn't be pasted after this).
Public Sub CutInvoke this method to cut and paste in the Pasteboard the selected controls.
Public Sub DeleteSelectedControl()Deletes the selected Controls. This action is Undoable while a new action is not be done.
Public Sub FirstPage()Displays the first Page in the main Board.
Public Function GetCaptions() as captionTextArea()Returns all the Text Caption controls for all the available pages.
Public Function GetLastUndoActionText() as StringReturns the text of the last undoable action. Use this method, for example, to change the text shown by the “Undo” menu item in the app or Window MenuBar.
Public Function GetPage(pageNumber as integer) as PictureReturns a Picture with the same Width and Height set to the main Board (Page). The contents of the Picture is the rendition of the Controls and Captions (if visible) for the PageNumber received as parameter. If the PageNumber parameter is greater than the available pages, then it will return the rendition for the last page available.
Public Function GetPageItems() as RectControl()Returns all the Controls (without Text Captions) for the current displayed Page in the main Board.
Public Function GetPagesForRange(initialPage as integer, lastPage as integer) as Picture()Returns an Array of Pictures with the same Width and Height set to the main Board (Page). The contents of every Picture is the rendition of the Controls and Captions (if visible) for the range of pages received as parameters. If the LastPage parameter is greater than the available pages, then it will return the rendition for the last page available.
Public Sub GoToPage(page as Integer)Displays the layout for the page received as parameter in the main Board.
Public Function HasContentToPaste() as BooleanInvoke this method to know if there are contents to paste available in the AXControlGrid Pasteboard. For example, this is useful for enabling/disabling the Paste MenuItem in the App or Window MenuBar.
Public Function HasUndoItems() as BooleanInvoke this method to know if there are more undo actions available in the AXControlGrid Undo Stack. For example, this is useful for enabling/disabling the Undo MenuItem in the App or Window MenuBar.
Public Sub InitBoardSize(NewWidth as Integer, NewHeight as integer)Use this method to Init the main Board (and Page size) to the Width and Height passed as parameters. Unlike the method `SetBoardSize`, this action is not registered by the AXControlGrid Undo Stack.
Public Sub LastPage()Displays the layout for the last available Page.
Public Sub NextPage()Displays the layout for the next available Page.
Public Function PageCaptions() as CaptionTextArea()Returns an Array with the Text Captions Controls for the currently displayed page in the main Board.
Public Sub Paste()Paste the available Pasteboard contents at the user specified insertion point.
Public Sub PreviousPage()Displays the layout for the previous Page.
Public Sub selectAll()Selects all the contents for all the available pages in the main Board. AXControlGrid will draw a selection rectangle around every selected item.
Public Sub SetBoardSize(newWidth as integer, newHeight as Integer)Set the main Board (and Page) size to the Width and Height received as parameters. If the Text Captions are set to Visible and the new Height value is lower than that needed for the correct layout of the Controls plus the Text Captions, then this method will raise an Exception you can Catch to do further operations. The AXControlGrid will keep the layout in a stable status and the new Width and Height values will not be applied.
Public Sub SetControlWidthAndHeight(newWidth as Integer, newHeight as integer)Set the Controls size to the Width and Height received as parameters. This value will be applied to all the Controls for all the Pages, except for the Text Captions. Use the Method `CaptionHeight` if you need to change the TextCaption boxes height, the width will be adjusted to the width of the associated Controls.
Public Sub SetGutter(newValue as integer)Set the Gutter (margin) for the main Board Controls to the received parameter value. This setting is applied to the controls margins both vertically and horizontally (gap or gutter).
Public Sub Undo()Call this method to Undo the last action registered by the AXControlGrid Undo Stack.

Version History

VersionRelease DateDescription
1.03 October 2019Initial Release
1.0.110 October 2019Minor fix to the Demo Project so it runs “out of the box” with Xojo 2019r2
axcontrolgrid.txt · Last modified: 2019/10/10 20:01 by bloguintosh