User Tools

Site Tools


aximagecanvas

This is an old revision of the document!


AXImageCanvas

Canvas based UI control for Desktop Xojo 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 in the Store

You can buy your AXImageCanvas in the AprendeXojo Store using these links:

Differences among Edition Features

AXImageCanvas Standard and AXImageCanvas Database Editions share the same features except:

  • AXImageCanvas Standard Edition doesn't provides all the Database related features.

In order to get support for the available SQLite, MySQL and PostgreSQL CRUD features you need to upgrade your current AXImageCanvas Standard Edition or buy a new AXImageCanvas Database Edition.

Minimum Requirements

Since version 1.0.2, AXImageCanvas works with Xojo 2017r3 and later.

Supported Xojo Editions:

  • Xojo Lite
  • Xojo Desktop
  • Xojo Pro
  • Xojo Pro Plus

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.)

  • MySQLCommunityPlugin.xojo_plugin
  • PostgreSQLPlugin.xojo_plugin

Licensing AXImageCanvas

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”)

Replacing Name, Surname and Data values with the information got from AprendeXojo after purchasing the license.

Dragging Images From AXImageCanvas Instances

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.

Class Description

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.

How to use AXImageCanvas in your own projects (Install)

  • Open the AXImageCanvas Demo Xojo project provided in the product distribution.
  • Copy the AXImageCanvas Folder from the Project Browser.
  • Paste it into your own Xojo Project.

Supported Picture Formats

AXImageCanvas supports the following picture formats:

  • GIF (first frame)
  • JPEG
  • PNG
  • TIFF

AXImageCanvas and Databases

AXImageCanvas instances can be used in combination of any of the currently supported database engines (Database Edition):

  • SQLite.
  • MySQL / MariaDB.
  • PostgreSQL.

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!

Enabling Database Engines

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 NameDefault Value
SQLiteEnabledTrue
MySQLEnabledFalse
PostgreSQLEnabledFalse

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:

SQLiteMySQLPostgreSQLApp size
TrueTrueTrue43.1 MB
FalseTrueFalse40.2 MB
TrueFalseFalse37,7 MB
FalseFalseTrue38.2 MB

AXImageCanvas Properties

PropertyDescriptionStandard EditionDatabase Edition
AcceptDroppedImages As Boolean.When set, the instance accepts the dropped image files. Available through the Inspector Panel and Code.YesYes
BackgroundColor As Color.Set or Get the background color for the AXImageCanvas Instance. Available through the Inspector Panel and code.YesYes
Database As Database.Set or Get any of the supported databases engines. Available through the Inspector Panel and Code.NoYes
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.YesYes
DrawFrameBorder As Boolean.Set or Get the status so the AXImageCanvas based control draws its border. Available through the Inspector Panel and code.YesYes
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.YesYes
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.YesYes
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.YesYes
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.YesYes
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.NoYes
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.NoYes
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.NoYes
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.NoYes
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.NoYes
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.YesYes
RaiseDatabaseExceptions As BooleanSet 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 AppNoYes
SelectionDelegate As SelectionCallbackThis method is called when the control instance receives the Focus. Available through code.YesYes
TableName As String.Set or Get the name of the table responsible of the database features. Available through the Inspector Panel and code.NoYes

AXImageCanvas Methods

Method NameDescriptionStandard EditionDatabase 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.NoYes
DisplayDatabasePicture(withID As String) As BooleanDisplays the Picture associated with the received record ID.NoYes
FirstRecord()Displays the Picture for the first Record of the associated database table.NoYes
GetRowID() As IntegerReturns the ID for the current displayed record.NoYes
LastRecord()Displays the Picture for the last Record of the associated database table.NoYes
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.NoYes
NewRecord(Image as Picture)Inserts a new record in the Database setting the associated Picture column data to the received Picture.NoYes
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.NoYes
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.NoYes
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.NoYes

Event Handler Definitions

Event NameDescriptionStandard EditionDatabase Edition
ImageLoaded()Implement this Event Handler in the AXImageCanvas instance to be notified every time the control instance displays a new Picture.YesYes
ImageDeleted()Implement this Event Handler in the AXImageCanvas to be notified when the user (or code) deletes the AXImageCanvas instance picture.YesYes

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.

  • DoubleClick(X As Integer, Y As Integer)
  • GotFocus()
  • KeyDown(Key As String) As Boolean
  • LostFocus()
  • MouseDown(X As Integer, Y As Integer)
  • MouseDrag(X As Integer, Y as Integer)
  • MouseUp(X As Integer, Y as Integer)
  • Open

Releases History

VersionRelease DateSummary
1.0.2019-08-19Initial Release
1.0.12019-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.22019-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.02019-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.
aximagecanvas.1571020633.txt.gz · Last modified: 2019/10/14 04:37 by bloguintosh