AprendeXojo Docs

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== AXImageCanvas ======

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.

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

===== AXImageCanvas in the Store =====

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

  * [[https://www.aprendexojo.com/en/shop/aximagecanvas-standard-edition-2/|AXImageCanvas Standard Edition]]
  * [[https://www.aprendexojo.com/en/shop/aximagecanvas-database-edition/|AXImageCanvas Database Edition]]

==== 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, always you don't intend to use these database engines.)

  * MySQLCommunityPlugin.xojo_plugin
  * PostgreSQLPlugin.xojo_plugin

==== AXImageCanvas and Xojo API 1.0 and API 2.0 ====

Since version 1.2.0, AXImageCanvas folder contains two demo projects:

  * **AXImageCanvas API 1.** Use the class version found inside this Demo project with Xojo 2019r2 (or any of the previous supported releases), when your project uses API 1.0 code.
  * **AXImageCanvas API 2.** Use the class version found inside this Demo project with Xojo 2019r2 and later when your project uses API 2.0 code.

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


===== 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 Name^Default Value^
|SQLiteEnabled|True|
|MySQLEnabled|False|
|PostgreSQLEnabled|False|

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:

^SQLite^MySQL^PostgreSQL^App size^
|True|True|True|43.1 MB|
|False|True|False|40.2 MB|
|True|False|False|37,7 MB|
|False|False|True|38.2 MB|

===== AXImageCanvas Database Error Handling =====
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.

===== 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**.

===== AXImageCanvas Shared Properties =====
^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|

===== AXImageCanvas Shared Methods =====
^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|

===== AXImageCanvas Properties =====

^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|
===== AXImageCanvas Methods =====

^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 Handler Definitions =====

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

  * DoubleClick(X As Integer, Y As Integer) (API 1.0)
  * **DoubleClicked(X As Integer, Y As Integer)** (API 2.0)
  * 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 (API 1.0)
  * **Opening** (API 2.0)

===== AXImageCanvas Delegates Definition =====

^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|

===== Releases History =====

^Version^Release Date^Summary^
|1.0.|2019-08-19|Initial Release|
|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.|
AprendeXojo Docs

User Tools

Site Tools

Page Tools
