# AppKitAddition {% hint style="info" %} Module **macOS only! Some features are available for Windows too but physically located in** [**User32Addition**](/add-ons/cstruecolors/documentation/user32addition.md)**.** {% endhint %} ## Overview ### Classes | Overview | | | ------------------------------------------------------------------------------------------ | - | | [VisualEffectView](/add-ons/cstruecolors/documentation/appkitaddition/visualeffectview.md) | | ### Methods | Overview | | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Alpha](/add-ons/cstruecolors/documentation/appkitaddition.md#alpha-extends-w-as-window-assigns-value-as-integer-as-integer) | [AlternateImage](/add-ons/cstruecolors/documentation/appkitaddition.md#alternateimage-extends-as-pushbutton-assigns-pic-as-picture) | | [AlternateTemplate](/add-ons/cstruecolors/documentation/appkitaddition.md#alternatetemplate-extends-as-pushbutton-assigns-pic-as-picture) | [AlternateTitle](/add-ons/cstruecolors/documentation/appkitaddition.md#alternatetitle-extends-b-as-pushbutton-assigns-value-as-string-as-string) | | [BringToFront](/add-ons/cstruecolors/documentation/appkitaddition.md#bringtofront-extends-w-as-window) | [Content](/add-ons/cstruecolors/documentation/appkitaddition.md#content-extends-p-as-popupmenu-index-as-integer-assigns-value-as-containercontrol) | | [Draw](/add-ons/cstruecolors/documentation/appkitaddition.md#draw-extends-p-as-picture-optional-g-as-graphics-x-as-double-y-as-double-width-as-double-height-as-double-x1-as-double-0-y1-as-double-0-sourcewidth-as-double-1-sourceheight-as-double-1-operation-as-nscompositingoperation-nscompositingoperation-clear-opacity-as-double-1) | [DrawAsTemplate](/add-ons/cstruecolors/documentation/appkitaddition.md#drawastemplate-extends-p-as-picture-x-as-double-y-as-double-width-as-double-height-as-double) | | [Image](/add-ons/cstruecolors/documentation/appkitaddition.md#image-extends-s-as-pushbutton-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-position-as-nscellimageposition-nscellimageposition-imageleft-assigns-pic-as-picture) | [ImageHugsTitle](/add-ons/cstruecolors/documentation/appkitaddition.md#imagehugstitle-extends-b-as-pushbutton-assigns-value-as-boolean-as-boolean) | | [ImagePosition](/add-ons/cstruecolors/documentation/appkitaddition.md#imageposition-extends-b-as-pushbutton-assigns-value-as-nscellimageposition-as-nscellimageposition) | [Images](/add-ons/cstruecolors/documentation/appkitaddition.md#images-extends-parent-as-menuitem-s-as-menuitem-assigns-pics-as-picture) | | [ImageScaling](/add-ons/cstruecolors/documentation/appkitaddition.md#imagescaling-extends-b-as-pushbutton-assigns-value-as-nsimagescaling-as-nsimagescaling) | [MixedStateImage](/add-ons/cstruecolors/documentation/appkitaddition.md#mixedstateimage-extends-s-as-menuitem-assigns-pic-as-picture) | | [SizeToFit](/add-ons/cstruecolors/documentation/appkitaddition.md#sizetofit-extends-r-as-rectcontrol) | [Style](/add-ons/cstruecolors/documentation/appkitaddition.md#style-extends-p-as-popupmenu-assigns-value-as-appkitaddition-popupmenustyle-as-appkitaddition-popupmenustyle) | | [Template](/add-ons/cstruecolors/documentation/appkitaddition.md#template-extends-s-as-segmentedcontrol-index-as-integer-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-assigns-pic-as-picture) | | ### Enumerations | Overview | | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | [NSBackgroundStyle](/add-ons/cstruecolors/documentation/appkitaddition.md#nsbackgroundstyle) | [NSCellImagePosition](/add-ons/cstruecolors/documentation/appkitaddition.md#nscellimageposition) | | [NSCompositingOperation](/add-ons/cstruecolors/documentation/appkitaddition.md#nscompositingoperation) | [NSImageScaling](/add-ons/cstruecolors/documentation/appkitaddition.md#nsimagescaling) | | [PopupMenuStyle](/add-ons/cstruecolors/documentation/appkitaddition.md#popupmenustyle) | | ## Documentation ### Methods #### Alpha (extends w As Window / RectControl, Assigns Value As Integer) / As Integer Sets the transparency value of a Window or a RectControl to a value similar to a Xojo Color Alpha value. Works like a property, which means both is valid: `Dim Alpha As Integer = Window1.Alpha`\ `Canvas1.Alpha = 230` {% hint style="info" %} Use the MakeTransparent method on Windows for similar results. {% endhint %} #### AlternateImage(extends As PushButton / RadioButton, assigns pic As Picture) An alternate image that appears on the button when the button is in an on state. Example: `me.AlternativeImage = myPicture` #### AlternateTemplate(extends As PushButton / RadioButton, assigns pic As Picture) Like alternate image, but the template representation of the image is used. Example: `me.AlternativeTemplate = myPicture` #### AlternateTitle(extends b As PushButton / RadioButton, assigns value As String) / As String The title that the button displays when the button is in an on state. Works like a property, which means from inside a pusbutton: `me.AlternateTitle = "Systems online"`\ `Dim s as String = me.AlternateTitle` #### BringToFront (extends w As Window) \[`mac + win]` Brings a window to the foreground. #### Content (extends p As Popupmenu, Index As Integer, assigns value As ContainerControl) Assigns an containercontrol as a contentview to the item at the specified index of a popupmenu. Reset to normal cell by assigning Nil. #### Draw(extends p As Picture, *optional* g As Graphics, x As Double, y As Double, width As Double, height As Double, x1 As Double = 0, y1 As Double = 0, sourceWidth As Double = -1, sourceHeight As Double = -1, Operation as NSCompositingOperation = NSCompositingOperation.clear, Opacity as Double = 1 Draws the picture in the specified rectangle of the current CGGraphics context, with optional Blend Modes and opacity. Rest of the parameters are like graphics.DrawPicture. If g is defined, y values are inverted. #### DrawAsTemplate(extends p As Picture, *optional* g As Graphics, x As Double, y As Double, width As Double, height As Double, x1 As Double = 0, y1 As Double = 0, sourceWidth As Double = -1, sourceHeight As Double = -1, Operation as NSCompositingOperation = NSCompositingOperation.clear, Opacity as Double = 1 #### DrawAsTemplate(extends p As Picture, x As Double, y As Double, width As Double, height As Double) Like Picture.Draw in this mpdule, except for that the template representation of the picture is being used. #### Image(extends s As MenuItem, Scaling As NSImagescaling = NSImagescaling.none, Position As NSCellImageposition = NSCellImageposition.imageleft, assigns Pic As Picture) The image that appears on the menuitem when it’s in an off state, or nil if there should be no such image. {% hint style="info" %} Use the [Images](/add-ons/cstruecolors/documentation/appkitaddition.md#images-extends-parent-as-menuitem-s-as-menuitem-assigns-pics-as-picture) method for Windows. {% endhint %} #### Image(extends p As PopupMenu, Index As Integer, Scaling As AppkitAddition.NSImageScaling = AppkitAddition.NSImageScaling.None, Position As AppkitAddition.NSCellImagePosition = AppkitAddition.NSCellImagePosition.ImageLeft, assigns value As Picture) Assigns an image to item at index of a popupmenu. #### Image(extends s As PushButton / RadioButton, scaling As NSImageScaling = NSImageScaling.None, position As NSCellImageposition = NSCellImageposition.imageleft, assigns pic As Picture) `[mac + win]` Sets the image that appears on the button when it’s in an off state, or nil if there is no such image. {% hint style="info" %} Scaling and Position are ignored on Windows. {% endhint %} {% hint style="danger" %} This currently crashes the project under Windows silently when an image or template is assigned second time to a button – because of getting its handle, not because of the declare. {% endhint %} #### Image(extends s As SegmentedControl, Index as integer, scaling as NSImageScaling = NSImagescaling.ProportionallyUpOrDown, assigns pic As Picture) Sets the image of a segment to pic, using the specified scaling method. #### ImageHugsTitle(extends b As PushButton / RadioButton, assigns value As Boolean) / As Boolean A Boolean value that determines how the button’s image and title are positioned together within the button bezel. **Available** since macOS 10.12. `me.ImageHugsTitle = True"`\ `Dim b as Boolean = me.ImageHugsTitle` #### ImagePosition(extends b As PushButton / Radiobutton, assigns value As NSCellImagePosition) / As NSCellImagePosition Determines how image and title are placed inside a button cell. `me.ImagePosition = AppKitAddition.NSCellImagePosition.ImageLeft`\ `Dim p as AppKitAddition.NSCellImagePosition = me.ImagePosition` #### Images(extends parent As Menuitem, s As Menuitem, assigns pics() As Picture) `[mac + win]` Sets the offstate and onstate images for a menuitem. Here for compatibility with the Windows equivalent. #### ImageScaling(extends b As PushButton / RadioButton, assigns value As NSImageScaling) / As NSImageScaling The scaling mode applied to make the cell’s image fit the frame of the image view. `me.ImageScaling = AppKitAddition.NSImageScaling.None`\ `Dim s as AppKitAddition.NSImageScaling = me.ImageScaling` #### MixedStateImage(extends s As MenuItem, assigns Pic As Picture) The image of the menuitem that indicates a "mixed” state. #### SizeToFit(extends r As RectControl) Resizes a control to the size accomodating its content, if possible. {% hint style="info" %} Currently available for Push- and RadioButtons on Windows. {% endhint %} #### Style(extends p As PopupMenu, Assigns value As AppKitAddition.PopupMenuStyle) / As AppKitAddition.PopupMenuStyle Gets/sets the style of a popupmenu. #### Template(extends s As PushButton, scaling As NSImageScaling = NSImageScaling.ProportionallyUpOrDown, position As NSCellImageposition = NSCellImageposition.imageleft, assigns pic As Picture) `[mac + win]` Identical to [*Image*](/add-ons/cstruecolors/documentation/appkitaddition.md#image-extends-s-as-pushbutton-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-position-as-nscellimageposition-nscellimageposition-imageleft-assigns-pic-as-picture), only that here the template representation of the image is being used. (on Windows the ICON handle if possible) {% hint style="danger" %} This currently crashes the project under Windows silently when an image or template is assigned second time to a button – because of getting its handle, not because of the declare. {% endhint %} #### Template(extends s As SegmentedControl, Index as integer, scaling as NSImageScaling = NSImagescaling.ProportionallyUpOrDown, assigns pic As Picture) Identical to [*Image*](/add-ons/cstruecolors/documentation/appkitaddition.md#image-extends-s-as-segmentedcontrol-index-as-integer-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-assigns-pic-as-picture), only that here the template representation of the image is being used. ### Enumerations #### NSBackgroundStyle A style for the background appearance of a control. Values: | Value | Definition | | ---------- | ------------------------------------------------------------------------- | | Normal | Normal appearance | | Emphasized | An appearance that makes the control visually more important. | | Raised | The background is intended to appear higher than the content drawn on it. | | Lowered | The background is intended to appear lower than the content drawn on it. | #### NSCellImagePosition Works together with [*ImagePosition*](/add-ons/cstruecolors/documentation/appkitaddition.md#imageposition-extends-b-as-pushbutton-assigns-value-as-nscellimageposition-as-nscellimageposition), [*Image*](/add-ons/cstruecolors/documentation/appkitaddition.md#image-extends-s-as-segmentedcontrol-index-as-integer-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-assigns-pic-as-picture) and [*Template*](/add-ons/cstruecolors/documentation/appkitaddition.md#template-extends-s-as-pushbutton-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-position-as-nscellimageposition-nscellimageposition-imageleft-assigns-pic-as-picture) methods. Values: | Value | Definition | | ------------- | ------------------------------------------------------------------ | | NoImage | Shows no image. Default value for a control. | | ImageOnly | Shows only the image, no text. | | ImageLeft | Image is Left of the text. Default for Image and Template methods. | | ImageRight | Image is positioned on the right side of the text. | | ImageAbove | Image is positioned above the text. | | ImageOverlaps | Image is centered and may overlap the text. | #### NSCompositingOperation Blend mode for the Picture.Draw… methods. See #### NSImageScaling Values for the [*ImageScaling*](/add-ons/cstruecolors/documentation/appkitaddition.md#imagescaling-extends-b-as-pushbutton-assigns-value-as-nsimagescaling-as-nsimagescaling) methods: | Value | Definition | | ---------------------- | ------------------------------------------------------------ | | ProportionallyDown | Image is scaled proportionally down to fit into the control. | | AxesIndependently | Image is scaled unproportionally to fit into the control. | | None | No scaling. Image may overlap or be cut. | | ProportionallyUpOrDown | Proportional scaling, upwards too if necessary. | #### PopupMenuStyle | Value | Definition | | ------------- | ----------------------------------------------- | | StylePopup | The default style where item 0 is selectable. | | StylePulldown | Item 0 becomes the title and is not selectable. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://xojo.gitbook.io/add-ons/cstruecolors/documentation/appkitaddition.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.