Canvas based UI control for Xojo Desktop developers (Desktop Lite, Desktop, Pro and Pro Plus); both for 32 and 64 Bits deployments on macOS, Windows and Linux.
This Class is available as Standard Edition and Database Edition.
You can work with the AXImageCanvas class from the IDE without restrictions when running your own apps in Debug Mode; but a license is required when you're ready to Build any project containing this class.
AXImageCanvas greately simplifies the task of displaying a Picture into the containing control area (Width and Height), with the ability to correctly display the image maintaining its original aspect ratio whitout touching the original picture. This can be done from any dropped image from inside the app, via a Picture File dropped from the Desktop, or another Picture dropped from another AXImageCanvas control or executing App, plus any copied picture from another app or source. Of course, the displayed image can be set programmatically, just passing the desired Picture Object (instance).
If the dropped image comes from a File, then the AXImageCanvas instance will keep a reference to the original FolderItem, so it is possible to do additional operations on it.
AXImageCanvas supports the Copy, Paste, Cut, Clear (Delete) and Undo actions selected from the app menu or using the equivalent keyboard shortcuts.
You can buy your AXImageCanvas in the AprendeXojo Store using these links:
AXImageCanvas Standard and AXImageCanvas Database Editions share the same features except:
In order to get support for the available
PostgreSQL CRUD features you need to upgrade your current
AXImageCanvas Standard Edition or buy a new
AXImageCanvas Database Edition.
Since version 1.0.2, AXImageCanvas works with Xojo 2017r3 and later.
Supported Xojo Editions:
In order to run and use AXImageCanvas, please make sure that the following Xojo standard plug-ins are included in the Xojo
plugins folder. Restart the Xojo IDE if you need to copy them back to the Xojo
plugins folder. (This is not mandatory when using AXImageCanvas 1.1 and later, always you don't intend to use these database engines.)
Since version 1.2.0, AXImageCanvas folder contains two demo projects:
Once you get your AXImageCanvas license, you need to call the
License method prior to use any AXImageCanvas feature in your deployed applications. Usually, the
App.Open method is the best place to do that, using the following line of code:
AXImageCanvas.License(“Name”, “Surname”, “Data”)
Data values with the information got from AprendeXojo after purchasing the license.
AXImageCanvas supports the following picture formats:
AXImageCanvas instances can be used in combination of any of the currently supported database engines (Database Edition):
In these cases, and in addition of the previously described features, it will take care of the usual CRUD operations; getting the picture for the specified record, creating new records, updating the current record or deleting the current displayed record (more on this a bit later).
This class also brings methods and capture keyboard events allowing navigation throught the records: first record, last record, next record, previous record; even if their ID are not consecutives.
By default the navigation between records works in Loop Cycle mode, so if the user is displaying the picture for the first record and invokes the Previous record action, then it will display the last picture on the table database. Otherwhise, if the user is displaying the picture of the last record and invokes the Next record action, then the AXImageCanvas instance will display the first record of the table database.
This behaviour can be changed setting the LoopThroughRecords Property, in combination with the NavigateRecords property.
The database engine used by the control instances can be changed on the fly!
In order to enable and use any of the supported database engines, it's mandatory to set the associated Constant value to
True under the
AXImageCanvasEnabledDB public module (included in the AXImageCanvas Folder inside the Demo project). SQLite is the only database engine active by default in these constants:
AXImageCanvasEnabledDB Module default Constant values
|Constant Name||Default Value|
The reasoning behind this made this way is to ensure the support for Xojo Desktop Lite users, and the no inclusion of non-used Xojo databases plug-ins in the deployed applications using AXImageCanvas.
For example, this would be the Demo Project size compiled with several
AXImageCanvasEnabledDB combinations on macOS:
Since AXImageCanvas 1.2, the component is not silent about errors with the database operations / access, displaying by default a dialog for every database access error during any of the supported CRUD operations. This is configurable via the
RaiseDatabaseExceptions As Boolean property. When set to
True, the AXImageCanvas instance will raise an exception that must be catched by the calling code for the operation.
In order to start the Drag action from any AXImageCanvas Instance, press the
Command key while start dragging with the pointing device on macOS; press the
Alt key while start dragging with the pointing device on Windows and Linux.
|Property||Description||Standard Edition||Database Edition|
|APIVersion As Integer||Get the Xojo API version of the AXImageCanvas code. Values are 1 for API 1.0 and 2 for API 2.0||Yes||Yes|
|Version As String||Get the AXImageCanvas version.||Yes||Yes|
|Property||Description||Standard Edition||Database Edition|
|License(Name As String, Surname As String, Data as String)||Call this method to license the AXImageCanvas component in deployed applications.||Yes||Yes|
|Property||Description||Standard Edition||Database Edition|
|AcceptDroppedImages As Boolean.||When set, the instance accepts the dropped image files. Available through the Inspector Panel and Code.||Yes||Yes|
|BackgroundColor As Color.||Set or Get the background color for the AXImageCanvas Instance. Available through the Inspector Panel and code.||Yes||Yes|
|Database As Database.||Set or Get any of the supported databases engines. Available through the Inspector Panel and Code.||No||Yes|
|Draggable As Boolean.||Set or Get the ability for the app user to move the AXImageCanvas position inside the containing area (Window, ContainerControl or any RectControl based instance. Available through the Inspector Panel and code.||Yes||Yes|
|DrawFrameBorder As Boolean.||Set or Get the status so the AXImageCanvas based control draws its border. Available through the Inspector Panel and code.||Yes||Yes|
|HasResizeHandlers As Boolean.||Set or Get the status so the AXImageCanvas show Resizing Handlers to the app user. When set to true, the user can resize the control instance if it has the Focus.||Yes||Yes|
|Image As Picture.||Set or Get the Picture displayed by the AXImageCanvas instance. Every instance saves the original Picture and calculates a cached image to the current Width/Height of the control. Available through the Inspector Panel and code.||Yes||Yes|
|InformationEnabled As Boolean.||Set or Get the status for displaying a Image Information Window when the user presses the I key and the AXImageCanvas instance has the focus. Available through the Inspector Panel and code.||Yes||Yes|
|LiveResizingPreview As Boolean.||Set or Get the status so the AXImageCanvas instance displays the resized image while the control is being resized HasResizedHandlers needs to be set to True. Available through the Inspector Panel and code.||Yes||Yes|
|LoopThroughRecors As Boolean.||Set or Get the status so the AXImageCanvas cycles through the records of the assigned database. Available through the Inspector Panel and code.||No||Yes|
|NavigateRecords As Boolean.||Set or Get the ability to use the cursor keys to navigate through the picture database records when a control instance is associated with any of the supported databases. Available through the Inspector Panel and code.||No||Yes|
|PictureColumn As String.||Set or Get the name of the Table used for storing the AXImageCanvas picture. For this to work. This property works combined with the Database and (optionally) the PictureFilePathColumn properties. Available through the Inspector Panel and code.||No||Yes|
|PictureFile As FolderItem.||Set or Get a FolderItem pointing to a Picture File. The instance will keep the reference to the FolderItem and (if dessired) can save the FolderItem path to the table database. Available through the Inspector Panel and code.||No||Yes|
|PictureFilePathColumn as String.||Set or Get the column name of the table database in charge of keep the path to the FolderItem pointing to the Picture. Available through the Inspector Panel and code.||No||Yes|
|PreviewEnabled As Boolean.||Set or Get the ability to display an Image Preview Window for the current displayed picture of the control instance. Available Through the Inspector Panel and code.||Yes||Yes|
|RaiseDatabaseExceptions As Boolean||Set the management of database errors / Exceptions to the AXImageCanvas instance or raise them so they can be catched by the calling code. By default this is set to False, so they are catched from the instance. Set this Property to True so they can be raised along the responsibility chain of the App||No||Yes|
|SelectionDelegate As SelectionCallback||This method is called when the control instance receives the Focus. Available through code.||Yes||Yes|
|TableName As String.||Set or Get the name of the table responsible of the database features. Available through the Inspector Panel and code.||No||Yes|
|Method Name||Description||Standard Edition||Database Edition|
|DeleteRecord()||If the number of columns in the database table is equal to the number of columns used by the control instance, then this method will effectively deletes the associated record; otherwhise, it will delete the image (setting it to NULL) and (if set) the associated FolderItem path data from the table, keeping unalterated the data associated with the remaining columns of the table.||No||Yes|
|DisplayDatabasePicture(withID As String) As Boolean||Displays the Picture associated with the received record ID.||No||Yes|
|FirstRecord()||Displays the Picture for the first Record of the associated database table.||No||Yes|
|GetRowID() As Integer||Returns the ID for the current displayed record.||No||Yes|
|LastRecord()||Displays the Picture for the last Record of the associated database table.||No||Yes|
|License(name As String, Surname As String, License as String)||Licenses the AXImageCanvas Class for deployment in compiled apps.|
|NewRecord()||Inserts a new record in the Database setting the associated Picture column data to NULL.||No||Yes|
|NewRecord(Image as Picture)||Inserts a new record in the Database setting the associated Picture column data to the received Picture.||No||Yes|
|NewRecord(ImageFolderItem as FolderItem)||Inserts a new record in the Database setting the associated Picture column data to the Picture file referenced by the received FolderItem.||No||Yes|
|NextRecord()||Displays the Picture for the next record of the associated table database. If the current displayed record is the last one and the LoopThroughRecords property is set to True, then it will display the Picture from the first table database record.||No||Yes|
|PreviousRecord()||Displays the Picture for the previous record of the associated table database If the current displayed record is the first one and the LoopThroughRecords property is set to True, then it will display the Picture from the last table database record.||No||Yes|
|Event Name||Description||Standard Edition||Database Edition|
|ImageLoaded()||Implement this Event Handler in the AXImageCanvas instance to be notified every time the control instance displays a new Picture.||Yes||Yes|
|ImageDeleted()||Implement this Event Handler in the AXImageCanvas to be notified when the user (or code) deletes the AXImageCanvas instance picture.||Yes||Yes|
The following events are those from the Canvas class consumed by the AXImageCanvas and that are made available again to the created control instances. Add these Event Handlers in the AXImageCanvas instances to implement additional behaviour after the one implemented by the Class itself.
|Delegate Signature||Description||Standard Edition||Database Edition|
|SelectionCallback(Control As AXImageCanvas)||Use any method in your code with this signature to receive the AXImageCanvas instance that is selected (has the focus). For that, the method has to be assigned to the SelectionDelegate Property.||Yes||Yes|
|1.0.1||2019-09-07||[Add] Minor Changes and improvements. [New] Added selectionDelegate Property. [Fix] Now the project properly catch the exception when the path for the stored picture in the database is not reachable (for example using the provided example SQLite database).|
|1.0.2||2019-10-02||[Add] Backwards compatibility to work with Xojo 2017r3 and later. [New] AcceptDroppedImages property. When set, it accepts dropped image files. [New] ImageDeleted event. If implemented, this event fires when the user (or code) deletes the image from the instance. [Add] Other minor improvements based on customers requests.|
|1.1.0||2019-10-09||[Add] New AXImageCanvasEnabledDB public module to better manage the code associated with the supported databases engines at compilation time. That means, among other things, that any project using AXImageCanvas will not include the Xojo database plug-ins for those databases that are not in use in the App. [Change] The DoubleClicked Event Handler Definition is now DoubleClick so it not collides in Xojo 2019r2. [Improved] Compatibility with Xojo 2019r2 “out of the box”. The complete rewriting for API 2.0 is under testing.|
|1.2.0||2019-10-14||[Add] New API 2.0 version of AXImageCanvas, so it can be used in combination with any project started using the Xojo API 2.0 in Xojo 2019r2 and later. [Add] New RaiseDatabaseException Property to set the way every instance deals with Database access errors. By default it is set to False what means that it will display a dialog with the error information. When set to True it raises an Exception that must be catched by the calling code.[Improved] AXICL class.|