Skip to content

Managing Backgrounds

Jump to bottom
rtrouton edited this page Mar 30, 2023 · 4 revisions

It is possible to manage the following settings for Backgrounds. An example configuration profile is available via the link below:

Backgrounds macOS configuration profile

Please see below for details on what can be managed:

Preference domain: corp.sap.Backgrounds

  • Key: HidePredefinedBackgrounds
  • Value: true or false
  • Note: This is a boolean value.

Description: If set to true, the predefined backgrounds included in the application (or specified using the PredefinedBackgrounds key), will not be displayed. If set to false, the predefined backgrounds cannot be hided by the user. If not specified (default), the predefined backgrounds are displayed and can be hided by the user.

  • Key: PredefinedBackgrounds
  • Value: A dictionary array

Description: This key allows to overwrite the predefined backgrounds included in the application, so administrators can define their own set of predefinded backgrounds. The dictionaries must look like this:

<key>PredefinedBackgrounds</key>
<array> 
<dict>
<key>BackgroundName</key>
<string>From gold to blue</string>
	<key>GradientColors</key>
<array>
	<integer>15772416</integer>
<integer>11051840</integer>
<integer>6265727</integer>
<integer>36819</integer>
</array>
<key>GradientLocations</key>
<array>
		<real>0</real>
<real>0.33</real>
<real>0.66</real>
<real>1</real>
</array>
<key>GradientAngle</key>
<integer>0</integer>
	<key>LogoName</key>
<string>My Logo</string>
<key>LogoSize</key>
<real>50</real>
<key>LogoXPosition</key>
<real>50</real>
<key>LogoYPosition</key>
<real>50</real>
<key>RadialGradient</key>
<false/>
</dict>

…

</array>

Explanation of the keys used in the sample code above:

  • Key: BackgroundName
  • Value: A string.

Description: The name of the background. This key is optional but must be used if the app should be used from the command line. If the name is not specified, the background does not show up if using the --listBackgrounds argument.

  • Key: GradientColors
  • Value: An array of integers.

Description: The colors of the gradient. Each number is the integer representation of the rgb value. So if you have e.g. a color like this: R: 250 G: 145 B: 0. This would be FA 91 00 in hex and converted to decimal this would be 16421120.

  • Key: GradientLocations
  • Value: An array of numbers (float or integer).

Description: Specifies the locations of the colors (configured using the GradientColors key).

  • Key: GradientAngle
  • Value: A number (float or integer)

Description: The angle of a linear gradient.

  • Key: RadialGradient
  • Value: true or false (boolean)

Description: Specifies if the gradient is radial (true) or linear (false or not specified).

Key: GradientXPosition Value: A number (float or integer) Description: Specifies the horizontal center of a radial gradient, starting with -1 at the left side of the background and ending with +1 at the right side.

  • Key: GradientYPosition
  • Value: A number (float or integer)

Description: Specifies the vertical center position of a radial gradient, starting with -1 at the bottom of the background and ending with +1 at the top.

  • Key: LogoName
  • Value: A string.

Description: The name of the logo image to embed into background image. The logo must be configured using the "LogoImages" key (see below). If the logo is not configured or the configured logo image does not exist, the app displays a small caution symbol instead of the logo image.

  • Key: LogoSize
  • Value: A number (float or integer)

Description: The size of the logo image in percent (%) of the size of the background image. This key overwrites the (fixed) size of the logo image, configured for the logo in "LogoImages".

  • Key: LogoXPosition
  • Value: A number (float or integer)

Description: The horizontal position of the logo image in percent (%). Starting with 0% at the left side of the background and ending with 100% at the right side. This key overwrites the (fixed) position of the logo image, configured for the logo in LogoImages.

  • Key: LogoYPosition
  • Value: A number (float or integer)

Description: The vertical position of the logo image in percent (%). Starting with 0% at the bottom of the background and ending with 100% at the top. This key overwrites the (fixed) position of the logo image, configured for the logo in LogoImages.

  • Key: LogoImages
  • Value: A dictionary array

Description: This key allows to specify logos that then can be embedded into the background image. The logo dictionaries must look like this:

<key>LogoImages</key>
<array>
<dict>
<key>LogoName</key>
<string>My Logo</string>
		<key>LogoPath</key>
<string>/Library/Application Support/Backgrounds/my_logo.pdf</string>
<key>LogoSize</key>
<integer>20</integer>
<key>LogoSizeLocked</key>
<true/>
<key>LogoXPosition</key>
<integer>50</integer>
<key>LogoXPositionLocked</key>
<true/>
<key>LogoYPosition</key>
<integer>50</integer>
<key>LogoYPositionLocked</key>
<true/>
</dict>
<dict>
<key>LogoName</key>
<string>My other logo</string>
		<key>LogoData</key>
<data>
	…
</data>
<key>LogoSize</key>
<integer>50</integer>
</dict>
</array>

Explanation of the keys used in the sample code above:

  • Key: LogoName
  • Value: A string.

Description: The logo name. This name is shown in the app's logo menu and must be unique.

  • Key: LogoPath
  • Value: A string.

Description: The path to an image file. Alternatively the logo can also be embedded in the configuration profile. Then use the key LogoData instead. If both, LogoPath and LogoData are specified, LogoPath is evaluated first and if no valid image file is found, LogoData is used.

  • Key: LogoData
  • Value: Base64 encoded image data.

Description: To get this data from an existing image file, you could use the Terminal and then so something like base64 -b 52 -i <path to file>. The output can be used as value for this key. If LogoPath is also defined, it would be evaluated first and only if it returns no valid image data, LogoData would be used.

  • Key: LogoSize
  • Value: A number (float or integer).

Description: The size of the logo image in percent (%) of the size of the background image. This optional key allows you to specify an initial size for the logo image.

  • Key: LogoSizeLocked
  • Value: true or false (boolean).

Description: An optional value that allows to lock the size of the logo image. If set to true, the size specified using the "LogoSize" key, cannot be changed by a user anymore. The logo size slider will be disabled. So if you want to make sure your logo is used in a specific size, specify the size and then lock it using this key.

  • Key: LogoXPosition
  • Value: A number (float or integer).

Description: The horizontal position of the logo image in percent (%). Starting with 0% at the left side of the background and ending with 100% at the right side. This optional key allows you to specify an initial horizontal position for the logo image.

  • Key: LogoXPositionLocked
  • Value: true or false (boolean).

Description: An optional value that allows to lock the horizontal position of the logo image. If set to true, the position specified using the LogoXPosition key, cannot be changed by a user anymore. The logo horizontal position slider will be disabled. So if you want to make sure your logo is displayed on a specific position of the background image, specify the position (using the LogoXPosition and LogoYPosition keys) and then lock the position using the LogoXPositionLocked and LogoXPositionLocked keys.

  • Key: LogoYPositionLocked
  • Value: true or false (boolean).

Description: An optional value that allows to lock the vertical position of the logo image. If set to true, the position specified using the LogoYPosition key, cannot be changed by a user anymore. The logo vertical position slider will be disabled. So if you want to make sure your logo is displayed on a specific position of the background image, specify the position (using the LogoXPosition and LogoYPosition keys) and then lock the position using the LogoXPositionLocked and LogoXPositionLocked keys.

  • Key: LogoYPosition
  • Value: A number (float or integer).

Description: The vertical position of the logo image in percent (%). Starting with 0% at the bottom of the background and ending with 100% at the top. This optional key allows you to specify an initial vertical position for the logo image.

Clone this wiki locally