This is an old revision of the document!
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:
AXControlGrid requires Xojo 2017r3 or later on macOS, and Xojo 2018r3 or later on Windows; both for generating 32 and 64 bit executables.
Supported Xojo Editions:
Both the AXControlGrid component and the provided Demo Project had been tested on the following Operating Systems versions:
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.
Call the License method on the BaseBoard class with the data received from AprendeXojo in order to license your copy of AXControlGrid:
Feel free to contact me if you are interested in an edition with no encrypted components (access to the source code).
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:
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:
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.
The main Board (or page) use these default values. You can always change them from code:
The final users of an app containing the AXControlGrid component will be able to do the following actions:
AXControlGrid can Undo the following actions:
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.
|Public Function AddControl(byref ControlTemplate as RectControl) as Boolean||Adds 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 CaptionTextArea||Returns 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 Cut||Invoke 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 String||Returns 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 Picture||Returns 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 Boolean||Invoke 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 Boolean||Invoke 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.|