[[:start|Start Page]] >> [[dragengine:modules:dragonscript:main|DragonScript Scripting Language]] >> [[dragengine:modules:dragonscript:guitheme|Gui Themes]] >> **Define XML Canvas Creator** ====== Canvas Creators ====== Canvas creators can be defined as parameters using the //canvasCreator// tag or inside own XML files typically with the extension //*.ccreator.xml//. The extension can be chosen differently if required. For both versions the same tag definition is used. Canvas creators are always based directly or indirectly on a type. This type is the //Canvas Creator Prototype// and defines what instance of //CanvasCreator// is used in the scripts. The choice of prototype affects the appearance of the canvas creator and the configuration possibilities. The following prototypes are provided by default by the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1CanvasCreators.html,CanvasCreators~@# script class: ^ Name ^ Script Class ^ Description ^ | [[#default|Default]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1DefaultCanvasCreator.html,DefaultCanvasCreator~@# | Empty canvas creator | | [[#rectangle|Rectangle]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1RectangleCanvasCreator.html,RectangleCanvasCreator~@# | Filled or empty rectangle | | [[#bevel|Bevel]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1BevelCanvasCreator.html,BevelCanvasCreator~@# | Filled or empty two-color bevelled border | | [[#image|Image]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1ImageCanvasCreator.html,ImageCanvasCreator~@# | Image stretched across entire canvas | | [[#imageborder|ImageBorder]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1ImageBorderCanvasCreator.html,ImageBorderCanvasCreator~@# | Up to 9 images creating size adapting border | You can use custom prototypes by adding them to #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1CanvasCreators.html,CanvasCreators~@# instance before loading gui themes. This is useful if you created custom canvas creator subclasses requiring custom parameters. This example defines a canvas creator based on the //Image// prototype displaying //canvasImage.png// stretched across entire canvas size. canvasImage.png If you modify an existing canvas creator the type of the original canvas creator is taken over. This example creates a canvas creator by loading it from a file and then replaces the image used. anotherCanvasImage.png ====== Canvas Creator Parameters ====== Canvas creators are configured by setting parameters. For each supported parameter type an own tag exists. See [[dragengine:modules:dragonscript:xmlguitheme:parameters|Defining Parameters]] for an overview of the supported types. The supported parameters by canvas creator type are listed below. ===== Default ===== The most basic canvas creator creating no canvas creator at all (empty canvas creator). Creates an instance of the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1DefaultCanvasCreator.html,DefaultCanvasCreator~@# script class. This is useful to set an empty canvas creator. As such it has no parameters at all. ===== Rectangle ===== Creates a canvas creator drawing a rectangle with optional fill color. Creates an instance of the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1RectangleCanvasCreator.html,RectangleCanvasCreator~@# script class. Both the rectangle and fill color are optional. These parameters can be used: ^ Parameter Name ^ Supported parameter type ^ Description ^ | colorFill | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color|Color]] | Color to use to fill the rectangle. Set to null or use a color with alpha value of 0 to not fill the rectangle | | colorLine | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color|Color]] | Color to use to outline the rectangle. Set to null or use a color with alpha value of 0 to not outline the rectangle | | thickness | [[dragengine:modules:dragonscript:xmlguitheme:parameters#floating_point|Floating Point]] | Thickness in pixels of the rectangle outline. Default is 1px width. | ===== Bevel ===== Creates a canvas creator drawing a bevelled rectangle with optional fill color. Creates an instance of the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1BevelCanvasCreator.html,BevelCanvasCreator~@# script class. Both the rectangle and fill colors are optional. These parameters can be used: ^ Parameter Name ^ Supported parameter type ^ Description ^ | colorHilight | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color|Color]] | Color to use for the hilight part of the rectangle outline | | colorShadow | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color|Color]] | Color to use for the shadow part of the rectangle outline | | colorBackground | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color|Color]] | Color to use to fill the rectangle. Set to null or use a color with alpha value of 0 to not fill the rectangle | | colorMatrix | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color_matrix|ColorMatrix]] | Color matrix to use for the entire canvas. | ===== Image ===== Creates a canvas creator stretching an image across the entire canvas size. Creates an instance of the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1ImageCanvasCreator.html,ImageCanvasCreator~@# script class. The image is optional. If not set this is the same as the default canvas creator. These parameters can be used: ^ Parameter Name ^ Supported parameter type ^ Description ^ | image | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to stretch across the entire canvas size | | colorMatrix | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color_matrix|ColorMatrix]] | Color matrix to use for the canvas. | ===== ImageBorder ===== Creates a canvas creator using up to 9 images to draw a size adapting border. The set of images composes of a center, side images and corner images. The corner images are placed at their original size in each corner. The side images are stretched along the respective border between the corners. The center is stretched to touch all corners. Creates an instance of the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CanvasCreators_1_1ImageBorderCanvasCreator.html,ImageBorderCanvasCreator~@# script class. All images are optional. Make sure the sizes of the images match. For example the top-left corner, top-right corner and top side images should have the same height. Otherwise gaps can result. If the canvas gets too small all images are scaled down to fit. This can be a suboptimal result so try to keep widgets using this canvas creator at a reasonable size. These parameters can be used: ^ Parameter Name ^ Supported parameter type ^ Description ^ | center | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use at the center of the border. Stretched to fit the all corners | | sideLeft | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as left side of the border. Stretched top-bottom to fit corners | | sideTop | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as top side of the border. Stretched left-right to fit corners | | sideRight | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as right side of the border. Stretched top-bottom to fit corners | | sideBottom | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as bottom side of the border. Stretched left-right to fit corners | | cornerTopLeft | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as top-left corner of the border. Placed at original size in the corner | | cornerTopRight | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as top-right corner of the border. Placed at original size in the corner | | cornerBottomLeft | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as bottom-left corner of the border. Placed at original size in corner | | cornerBottomRight | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as bottom-right corner of the border. Placed at original size in corner | | colorMatrix | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color_matrix|ColorMatrix]] | Color matrix to use for the canvas. |