Documentation

## Access Property Values

### Object Properties and Dot Notation

Graphing functions return the object or objects created by the function. For example:

`h = plot(1:10);`

`h` refers to the line drawn in the graph of the values 1 through 10.

Dot notation is a new syntax to access object properties starting in R2014b. This syntax uses the object variable and the case-sensitive property name connected with a dot (`.`) to form an object dot property name notation:

object.PropertyName

If the object variable is nonscalar, use indexing to refer to a single object:

object(n).PropertyName

#### Scalar Object Variable

If `h` is the line created by the `plot` function, the expression `h.Color` is the value of this particular line’s `Color` property:

```h.Color ```
```ans = 0 0.4470 0.7410```

If you assign the color value to a variable:

```c = h.Color; ```

The variable `c` is a double.

`whos`
``` Name Size Bytes Class c 1x3 24 double h 1x1 112 matlab.graphics.chart.primitive.Line ```

You can change the value of this line’s `Color` property with an assignment statement:

`h.Color = [0 0 1];`

Use dot notation property references in expressions:

`meanY = mean(h.YData);`

Or to change the property value:

`h.LineWidth = h.LineWidth + 0.5;`

Reference other objects contained in properties with multiple dot references:

```h.Annotation.LegendInformation.IconDisplayStyle ```
```ans = on```

Set the properties of objects contained in properties:

```ax = gca; ax.Title.FontWeight = 'normal';```

#### Nonscalar Object Variable

Graphics functions can return an array of objects. For example:

```y = rand(5); h = plot(y); size(h)```
```ans = 5 1```

Access the line representing the first column in `y` using the array index:

`h(1).LineStyle = '--';`

Use the `set` function to set the `LineStyle` of all the lines in the array:

`set(h,'LineStyle','--')`

#### Appending Data to Property Values

With dot notation, you can use “end” indexing to append data to properties that contain data arrays, such as line `XData` and `YData`. For example, this code updates the line `XData` and `YData` together to grow the line. You must ensure the size of line’s x- and y-data are the same before rendering with the call to `drawnow` or returning to the MATLAB® prompt.

```h = plot(1:10); for k = 1:5 h.XData(end + 1) = h.XData(end) + k; h.YData(end + 1) = h.YData(end) + k; drawnow end```

### Graphics Object Variables Are Handles

The object variables returned by graphics functions are handles. Handles are references to the actual objects. Object variables that are handles behave in specific ways when copied and when the object is deleted.

#### Copy Object Variable

For example, create a graph with one line:

`h = plot(1:10);`

Now copy the object variable to another variable and set a property value with the new object variable:

```h2 = h; h2.Color = [1,0,0]```

Assigning the object variable `h` to `h2` creates a copy of the handle, but not the object referred to by the variable. The value of the `Color` property accessed from variable `h` is the same as that accessed from variable `h2`.

`h.Color`
```ans = 1 0 0```

`h` and `h2` refer to the same object. Copying a handle object variable does not copy the object.

#### Delete Object Variables

There are now two object variables in the workspace that refer to the same line.

`whos`
``` Name Size Bytes Class h 1x1 112 matlab.graphics.chart.primitive.Line h2 1x1 112 matlab.graphics.chart.primitive.Line```

Now close the figure containing the line graph:

`close gcf`

The line object no longer exists, but the object variables that referred to the line do still exist:

`whos`
``` Name Size Bytes Class h 1x1 112 matlab.graphics.chart.primitive.Line h2 1x1 112 matlab.graphics.chart.primitive.Line```

However, the object variables are no longer valid:

`h.Color`
`Invalid or deleted object.`
`h2.Color = 'blue'`
`Invalid or deleted object.`

To remove the invalid object variables, use `clear`:

`clear h h2`

### Listing Object Properties

To see what properties an object contains, use the `get` function:

`get(h)`

MATLAB returns a list of the object properties and their current value:

``` AlignVertexCenters: 'off' Annotation: [1x1 matlab.graphics.eventdata.Annotation] BeingDeleted: 'off' BusyAction: 'queue' ButtonDownFcn: '' Children: [] Clipping: 'on' Color: [0 0.4470 0.7410] ... LineStyle: '-' LineWidth: 0.5000 Marker: 'none' ...```

You can see the values for properties with an enumerated set of possible values using the `set` function:

`set(h,'LineStyle')`
``` '-' '--' ':' '-.' 'none'```

To display all settable properties including possible values for properties with an enumerated set of values, use `set` with the object variable:

`set(h)`

### Modify Properties with set and get

You can also access and modify properties using the `set` and `get` functions.

The basic syntax for setting the value of a property on an existing object is:

`set(object,'PropertyName',NewPropertyValue)`

To query the current value of a specific object property, use a statement of the form:

`returned_value = get(object,'PropertyName');`

Property names are always character vectors. You can use single quotes or a variable that is a character vector. Property values depend on the particular property.

### Multi Object/Property Operations

If the object argument is an array, MATLAB sets the specified value on all identified objects. For example:

```y = rand(5); h = plot(y); ```

Set all the lines to red:

`set(h,'Color','red')`

To set the same properties on a number of objects, specify property names and property values using a structure or cell array. For example, define a structure to set axes properties appropriately to display a particular graph:

```view1.CameraViewAngleMode = 'manual'; view1.DataAspectRatio = [1 1 1]; view1.Projection = 'Perspective';```

To set these values on the current axes, type:

`set(gca,view1)`

#### Query Multiple Properties

You can define a cell array of property names and use it to obtain the values for those properties. For example, suppose you want to query the values of the axes “camera mode” properties. First, define the cell array:

```camModes = {'CameraPositionMode','CameraTargetMode',... 'CameraUpVectorMode','CameraViewAngleMode'};```

Use this cell array as an argument to obtain the current values of these properties:

```get(gca,camModes) ```
```ans = 'auto' 'auto' 'auto' 'auto'```