---
description: >-
  Adds extended image and color handling features to Xojo controls. Currently
  PushButton, RadioButton, PopupMenu, Window, MenuItem and SegmentedControl.
---

# AppKitAddition

{% hint style="info" %}
Module

**macOS only! Some features are available for Windows too but physically located in** [**User32Addition**](user32addition)**.**&#x20;
{% endhint %}

## Overview

### Classes

| Overview                                            |   |
| --------------------------------------------------- | - |
| [VisualEffectView](appkitaddition/visualeffectview) |   |

### Methods

| Overview                                                                                                                                                                                                                                                                               |                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [Alpha](#alpha-extends-w-as-window-assigns-value-as-integer-as-integer)                                                                                                                                                                                                                | [AlternateImage](#alternateimage-extends-as-pushbutton-assigns-pic-as-picture)                                         |
| [AlternateTemplate](#alternatetemplate-extends-as-pushbutton-assigns-pic-as-picture)                                                                                                                                                                                                   | [AlternateTitle](#alternatetitle-extends-b-as-pushbutton-assigns-value-as-string-as-string)                            |
| [BringToFront](#bringtofront-extends-w-as-window)                                                                                                                                                                                                                                      | [Content](#content-extends-p-as-popupmenu-index-as-integer-assigns-value-as-containercontrol)                          |
| [Draw](#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](#drawastemplate-extends-p-as-picture-x-as-double-y-as-double-width-as-double-height-as-double)        |
| [Image](#image-extends-s-as-pushbutton-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-position-as-nscellimageposition-nscellimageposition-imageleft-assigns-pic-as-picture)                                                                                           | [ImageHugsTitle](#imagehugstitle-extends-b-as-pushbutton-assigns-value-as-boolean-as-boolean)                          |
| [ImagePosition](#imageposition-extends-b-as-pushbutton-assigns-value-as-nscellimageposition-as-nscellimageposition)                                                                                                                                                                    | [Images](#images-extends-parent-as-menuitem-s-as-menuitem-assigns-pics-as-picture)                                     |
| [ImageScaling](#imagescaling-extends-b-as-pushbutton-assigns-value-as-nsimagescaling-as-nsimagescaling)                                                                                                                                                                                | [MixedStateImage](#mixedstateimage-extends-s-as-menuitem-assigns-pic-as-picture)                                       |
| [SizeToFit](#sizetofit-extends-r-as-rectcontrol)                                                                                                                                                                                                                                       | [Style](#style-extends-p-as-popupmenu-assigns-value-as-appkitaddition-popupmenustyle-as-appkitaddition-popupmenustyle) |
| [Template](#template-extends-s-as-segmentedcontrol-index-as-integer-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-assigns-pic-as-picture)                                                                                                                            |                                                                                                                        |

### Enumerations

| Overview                                          |                                             |
| ------------------------------------------------- | ------------------------------------------- |
| [NSBackgroundStyle](#nsbackgroundstyle)           | [NSCellImagePosition](#nscellimageposition) |
| [NSCompositingOperation](#nscompositingoperation) | [NSImageScaling](#nsimagescaling)           |
| [PopupMenuStyle](#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.&#x20;

#### 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](#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.&#x20;

#### 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_](#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_](#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_](#imageposition-extends-b-as-pushbutton-assigns-value-as-nscellimageposition-as-nscellimageposition), [_Image_](#image-extends-s-as-segmentedcontrol-index-as-integer-scaling-as-nsimagescaling-nsimagescaling-proportionallyupordown-assigns-pic-as-picture) and [_Template_](#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 [https://developer.apple.com/documentation/appkit/nscompositingoperation](https://developer.apple.com/documentation/appkit/nscompositingoperation)

#### NSImageScaling

Values for the [_ImageScaling_](#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. |
