Light Properties

Control light appearance and behavior

Light properties control the appearance and behavior of light objects. By changing property values, you can modify certain aspects of the light.

Starting in R2014b, you can use dot notation to refer to a particular object and property:

h = light;
c = h.Color;
h.Style = 'local';

If you are using an earlier release, use the get and set functions to query and set properties.

Color, Position, and Style

expand all

ColorColor of light[1 1 1] (default) | RGB triplet | color string

Color of light emanating from the light object, specified as an RGB triplet or a color string. The default RGB triplet of [1 1 1] corresponds to white.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Example: 'green'

PositionLocation of light source[1 0 1] (default) | three-element vector of the form [x y z]

Location of light source, specified as a three-element vector of the form [x y z]. Define the vector elements in data units from the axes origin to the (x, y, z) coordinate. The actual location of the light depends on the value of the Style property.

Example: [-40 -4 140]

StyleType of light source'infinite' (default) | 'local'

Type of light source, specified as one of these values:

  • 'infinite' — Place the light at infinity. Use the Position property to specify the direction from which the light shines in parallel rays.

  • 'local' — Place the light at the location specified by the Position property. The light is a point source that radiates from the location in all directions.

Visibility

expand all

VisibleVisibility of light from light source'on' (default) | 'off'

Visibility of light from light source, specified as 'on' or 'off'.

Parent and Children

expand all

ParentParent of lightaxes object | group object | transform object

Parent of light, specified as an axes, group, or transform object.

ChildrenChildren of lightempty GraphicsPlaceholder array

The light has no children. You cannot set this property.

HandleVisibilityVisibility of object handle'on' (default) | 'off' | 'callback'

Visibility of object handle in the Children property of the parent, specified as one of these values:

  • 'on' — List the light object.

  • 'off' — Do not list the light object. Use this option to hide object handles when a callback invokes a function that could damage the GUI, such as evaluating a user-typed string.

  • 'callback' — List the light object in the Children property of the parent from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. Use this option to protect a GUI from command-line users, while allowing callbacks to have access to objects.

If the light object is not listed in the Children property of the parent, then functions that obtain object handles by searching the object hierarchy or querying handle properties cannot return it. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

Hidden object handles are still valid. Set the root ShowHiddenHandles property to 'on' to list all object handles regardless of their HandleVisibility property setting.

Identifiers

expand all

TypeType of graphics object'light'

This property is read only.

Type of graphics object, returned as the string 'light'. Use this property to find all objects of a given type within a plotting hierarchy, for example, searching for the type using findobj.

TagTag to associate with light'' (default) | string

Tag to associate with the light, specified as a string. Tags provide a way to identify graphics objects. Use this property to find all objects with a specific tag within a plotting hierarchy, for example, searching for the tag using findobj.

Example: 'January Data'

UserDataData to associate with light[] (default) | scalar, vector, or matrix | cell array | character array | table | structure

Data to associate with the light object, specified as a scalar, vector, matrix, cell array, character array, table, or structure. MATLAB® does not use this data.

To associate multiple sets of data or to attach a field name to the data, use the getappdata and setappdata functions.

Example: 1:100

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | struct | table | cell

Creation and Deletion Control

expand all

CreateFcnCreation callback'' (default) | function handle | cell array | string

Creation callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • String that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you create the light. Setting the CreateFcn property on an existing light has no effect. You must define a default value for this property, or define this property using a Name,Value pair during light creation. MATLAB executes the callback after creating the light and setting all of its properties.

If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • The light object — You can access properties of the light object from within the callback function. You also can access the light object through the CallbackObject property of the root, which can be queried using the gcbo function.

  • Event data — This argument is empty for this property. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, see Callback Definition.

Example: @myCallback

Example: {@myCallback,arg3}

DeleteFcnDeletion callback'' (default) | function handle | cell array | string

Deletion callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • String that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you delete the light. MATLAB executes the callback before destroying the light so that the callback can access its property values.

If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • The light object — You can access properties of the light object from within the callback function. You also can access the light object through the CallbackObject property of the root, which can be queried using the gcbo function.

  • Event data — This argument is empty for this property. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, see Callback Definition.

Example: @myCallback

Example: {@myCallback,arg3}

BeingDeletedDeletion status of light'off' (default) | 'on'

This property is read only.

Deletion status of light, returned as 'on' or 'off'. MATLAB sets the BeingDeleted property to 'on' when the delete function of the light begins execution (see the DeleteFcn property). The BeingDeleted property remains set to 'on' until the light no longer exists.

Check the value of the BeingDeleted property to verify that the light is not about to be deleted before querying or modifying it.

Unused Properties

expand all

ButtonDownFcn(unused) Mouse-click callback'' (default) | function handle | cell array | string

Light objects do not use this property.

UIContextMenu(unused) Context menuuicontextmenu object

Light objects do not use this property.

Selected(unused) Selection state'off' (default) | 'on'

Light objects do not use this property.

SelectionHighlight(unused) Display of selection handles when selected'on' (default) | 'off'

Light objects do not use this property.

PickableParts(unused) Ability to capture mouse clicks'visible' (default) | 'none'

Light objects do not use this property.

HitTest(unused) Response to captured mouse clicks'on' (default) | 'off'

Light objects do not use this property.

Interruptible(unused) Callback interruption'on' (default) | 'off'

Light objects do not use this property.

BusyAction(unused) Callback queuing'queue' (default) | 'cancel'

Light objects do not use this property.

Was this topic helpful?