CRC.Press A Guide to MATLAB Object Oriented Programming May.2007 Episode 2 Part 5 potx

FIGURE 18.4 Class Wizard, cLineStyle public variable dialog... To define a new constructor, the TABLE 18.2 cLineStyle Public Member Variable Field Values Public Variable Accessor Express

exercise of entering private variables in §18.1.2, the fields Name and Comment are familiar The

type, accessor, and mutator fields are new

The type field serves two purposes First, with the exception of display, the public name and its type string are copied into all group-of-eight headers Second, the type string is displayed

as a hint when set is called with one argument That also means the type string is copied into the

–possible case inside fieldnames

Accessor Expression and Mutator Expression fields guide the generation of public cases inside get.m and set.m If the Expression field contains the name of a private variable, direct-access code syntax will be inserted into get or set If the Expression field contains the string %helper, helper-function syntax will be inserted into get or set, and a stub for the helper will be generated Finally, if the Expression field is empty, a public case for the variable

is not included The Accessor Expression value and Mutator Expression value are independent Accessor Expression influences the code in get and Mutator Expression

influences the code in set In addition, public variables with an empty Accessor Expression

value are not included in fieldnames or struct

All public variables in cLineStyle have accessors The accessor for Color uses a helper, but accessors for LineWidth and LineHandle are directly linked to mLineWidth and

mLineHandle All public variables also have mutators In this case, the mutator for LineWidth

is not a direct link but rather uses a helper The table of entries for the public variables is given in Table 18.2

The procedure for data entry follows the same procedure used for private variables Select the first empty line in the lower display block, and enter data in the fields After all field values have been specified, click Save Change to commit the data and move to the next line In this dialog, the lower display can’t be easily formatted using standard MATLAB syntax Instead, the lower display delimits each field by putting two colons between each value The display order is name, type, accessor, mutator, and comment When you have finished all additions or modifications, click

Done to commit the changes and return to the main dialog

FIGURE 18.4 Class Wizard, cLineStyle public variable dialog.

If you compare the generated group-of-eight files with files from Chapter 16, the code lines are identical Because of this, you will have no trouble relating the code to discussions in the previous chapters Ideally, you will never need to hand tailor any function in the group of eight, but if do, you should have no trouble finding your way

Accessor and mutator helper functions are another matter These private functions require tailoring because the dialog data do not include any information that could be used to generate class-specific code The functions include header information and they include code stubs that allow them to work without error This allows group-of-eight mechanics to be tested prior to tailoring, but the class is not fully functional until afterward We revisit the topic of helper file tailoring in

§18.1.7

18.1.4 C L INE S TYLE C ONSTRUCTOR F UNCTIONS

The final data-entry button on the main dialog defines constructors The cLineStyle class uses

a two-argument constructor to assign values for Color and LineWidth Click the Construc-tors button to display the dialog shown in Figure 18.5 To define a new constructor, the

TABLE 18.2

cLineStyle Public Member Variable Field Values

Public Variable

Accessor Expression

Mutator Expression Comment

LineWidth integer > 0 mLineWidth %helper

LineHandle graphics handle mLineHandle mLineHandle Public

graphics handle to the line plot

FIGURE 18.5 Class Wizard, cLineStyle constructor function dialog.

only data required are a comma-separated list of input variable names The function name is created based on the number of variables The comma-separated variable list is entered in the Input Argument List field Any valid variable name except this can be used in the list

For this example, we don’t need a table of dialog values Select the first empty line in the lower display Then type color, width into the Input Argument List field When you are done, click Save Change to commit the data Finally, click Done to return to the main dialog During file generation, Class Wizard will use this data to generate a function stub named

private/ctor_2.m The stub contents are shown in Code Listing 106 The comma-separated list from the definition data shows up in the input argument list of the function definition These variable names also show up in the header on lines 12 and 14 The comments list them as having

no type info and no description because data dictionary data for these variables do not yet exist The generated code is found in lines 27–31 The function will run; however, until it is tailored, line 29 will display a warning The helper can be tailored by copying code from the Chapter 16 version

Code Listing 106, Two-Input Class Wizard Constructor, @cLineStyle/private/ctor_2.m function this = ctor_2(this, color, width)

1 function this = ctor_2(this, color, width)

2 %CTOR_2 for class cLineStyle, Replace with a short note

3 % Replace with something like UNCLASSIFIED

5 % function this = ctor_2(this, color, width)

7 % Replace with text that you would like to have copied into the header of

8 % every file in this class

10 % Input Arguments::

11 %

12 % color: no type info: no description provided

13 %

14 % width: no type info: no description provided

15 %

16 % Author Info

17 % Replace with your company's name

18 % Replace with your name

19 % Replace with your email address

20 % Replace with your phone number

21 % Replace with the author notes that you would like to appear just after

22 % the author info for every file in this class

23 % Replace with your standard copyright notice

24 % Replace with a string recognized by your revision control software

25 % A Class Wizard v.3 assembled file, generated: 20-Dec-2005 13:23:23

26

18.1.5 C L INE S TYLE D ATA D ICTIONARY

At this point in the definition, public and private variables are defined and an additional constructor

is available From the main screen, you could generate all required files for a fully functioning

cLineStyle class But don’t click Build Class Files because there is one more dialog that needs attention We need to add comments so the header inside ctor_2 will contain mean-ingful comments for its input arguments

On the menu bar of the main dialog, select Data::Dictionary … This selection will display the dialog shown in Figure 18.6 These fields are similar to the same fields in the public variable dialog Initially the lower display should include the variable names color and width

but there will be no type or comments The variable names in the lower display were collected from the argument definitions used to define constructors, public functions, and private functions Since cLineStyle uses the standard set of public and private functions, the list only includes constructor arguments The data dictionary dialog can’t be used to add variables Variables are added automatically based on function definitions

The type and comment data you need are provided in Table 18.3 Select each variable by pointing to its line in the lower display and clicking The field values are now active and can be modified Click Save Change to commit the changes before selecting the next name After entering all the data, click Done to return to the main dialog Now if you generate the files, the header in ctor_2 will contain meaningful comments The affected lines now look like the following:

27 % \/ \/ \/ \/

28 % replace with your specific constructor code

29 warning('OOP:incompleteFunction',

30 'The function definition is incomplete');

31 % /\ /\ /\ /\

32 % Replace with something like UNCLASSIFIED

FIGURE 18.6 Class Wizard, cLineStyle data dictionary dialog.

% Input Arguments::

%

% color: 3x1 RGB values 0-1: The initial RGB line color The

% array is a 3x1 column vector of values and the values

%

% width: integer > 0: The initial line width as an integer

18.1.6 C L INE S TYLE B UILD C LASS F ILES

The definition for cLineStyle is now complete Click Build Class Files to begin class file generation You always need to specify a destination class directory MATLAB’s standard directory-selection dialog is used An example of the dialog is shown in Figure 18.7 Simply highlight the desired directory and click OK. If a suitable directory does not exist, the Make New Folder button on the lower left will allow you to create one When you click OK, Class Wizard

TABLE 18.3

cLineStyle Data Dictionary Field Values

Variable

color 3x1 RGB values

0-1

The initial RGB line color The array is

a 3x1 column vector of values and the values range from zero to one.

width integer > 0 The initial line width as an integer

greater than 0

FIGURE 18.7 Class Wizard, cLineStyle directory-selection dialog.

generates class files File generation is very fast Click Okay on the confirmation dialog to return

to the main Class Wizard dialog The newly generated class should work without error; however,

a couple of helper functions need to be tailored before the class will achieve full functionality These functions are discussed next

18.1.7 C L INE S TYLE A CCESSOR AND M UTATOR H ELPER F UNCTIONS

In cLineStyle three private helper functions need to be tailored The first is ctor_2, a private constructor helper The generated file was shown in Code Listing 106 Modifying the as-generated file is easy because we can copy the code body from the working version in Chapter 16 Refer to Code Listing 89 to see the complete function body

Code bodies for the other two helpers, Color_helper and LineWidth_helper, can also be copied from Chapter 16 After copying the code bodies, cLineStyle is complete The tailored versions of Color_helper and LineWidth_helper are also included in this chapter’s source files Before moving to the other classes, let’s look at the initial helper-file stub The as-generated version of Color_helper is shown in Code Listing 107 The listing consists mostly of comments, but there are some important lines of code in each case

Code Listing 107, Public Variable Helper, as Generated by Class Wizard,

cLineStyle::Color_helper

1 function [do_sub_indexing, do_assignin, this, varargout] = .

2 Color_helper(which, this, index, varargin)

3 %COLOR_HELPER for class cLineStyle, Replace with a short note

4 % Replace with something like UNCLASSIFIED

6 % function [do_sub_indexing, do_assignin, this, varargout]

=

7 % Color_helper(which, this, index, varargin)

9 % Replace with text that you would like to have copied into the header

10 % of every file in this class

11 %

12 % Author Info

13 % Replace with your company's name

14 % Replace with your name

15 % Replace with your email address

16 % Replace with your phone number

17 % Replace with the author notes that you would like to appear just

18 % after the author info for every file in this class

19 % Replace with your standard copyright notice

20 % Replace this line with a string for your revision control software

21 % A Class Wizard v.3 assembled file, generated: 18-Jan-2006 13:18:46

22 %

23

24 switch which

25 case 'get' % ACCESSOR

26 % input: index contains any additional indexing as a

substruct

27 % input: varargin empty for accessor

28 do_sub_indexing = true; % tells get.m whether to index

deeper

29 do_assignin = false; % leave false until you read book

section 3

30 varargout = cell(1, nargout-3); % -3, 3 known vars plus

varargout

33 % e.g., [varargout{:}] = {function of public and private

vars};

34 warning('OOP:incompleteFunction', .

35 'The function definition is incomplete');

37 case 'set' % MUTATOR

38 % input: index contains any additional indexing as a

substruct

39 % input: varargin contains values to be assigned into

the object

40 do_sub_indexing = false; % always false, mutator _must_

index

41 do_assignin = false; % leave false until you read book

section 3

42 varargout = {}; % 'set' returns nothing in varargout

44 % YOUR 'SET/MUTATOR' HELPER CODE GOES HERE

45 warning('OOP:incompleteFunction',

46 'The function definition is incomplete');

47 % below is a code template as a convenient starting point

48 % if isempty(index) % No more indexing requested, assign

input

49 % [this.Color] = deal(varargin{:});

50 % else % deeper indexing requested, use subsasgn to do it

51 % Color = [this.Color]; % Modify the assignment

52 % Color = subsasgn(Color, index, varargin{:});

56 otherwise

57 error('OOP:unsupportedOption', ['Unknown helper option: '

which]);

Lines 25–36 contain the placeholder for tailored accessor code Lines 28–29 assign typical flag values, and line 30 preallocates varargout based on the size of nargout These three lines are usually necessary so they are automatically included Lines 31–36 should be replaced by helper-specific accessor code Otherwise, lines 34–35 will generate a warning and return empty values

If accessor syntax is direct-link, there are two options depending on how much control is desired Either leave the warning in place or replace the warning with direct-link code

Lines 37–55 contain the placeholder for tailored mutator code Lines 40–41 assign typical flag values, and line 42 preallocates varargout Note that the mutator code must either use all the index values or throw an error Here varargout is empty because the object is returned in the output variable this These three lines are usually necessary so they are automatically included Lines 43–55 should be replaced by helper-specific mutator code Otherwise, lines 45–46 will generate a warning and an unmodified this will be returned The comments in lines 48–54 represent typical direct-link syntax and are included as an aid to development

18.2 CSHAPE CLASS WIZARD DEFINITION DATA

Data entry for every class follows the same procedure used to define cLineStyle During the definition of cShape, we will build on that procedure by spending more time discussing new areas Open a new session of Class Wizard or select File::New from the menu and type in

cShape as the class name From an earlier chapter, we know that cShape needs to be superior

to double In the Superior To: field on the main dialog, add the string double If cShape

needed to be superior to more than one type, a comma-separated list would be used Keep the default values for all other main dialog data The remaining definition data are entered using the various data-entry dialogs

18.2.1 C S HAPE H EADER I NFO

Click the Header Info … button and select Default Header Info::Load from the menu This selection loads the collection of default values previously saved during the definition of cLine-Style You can change the field values or leave them as is Click Okay to return to the main dialog

18.2.2 C S HAPE P RIVATE V ARIABLES

The next dialog for data entry defines the class’ private variables Click the

Private Variables … button and enter the data shown in Figure 18.8 The data are also summarized in Table 18.4 Data entry is the same as before First, select an empty line in the lower display block and start entering private variable data Click Save Change to commit the changes and move to the next line Finally, when data for all variables have been saved, click Done to return to the main dialog

The only noteworthy aspects of the private variables are the initial values The initial mPoints

array is now defined to be empty Previous versions of cShape used the corner points of a star

to populate mPoints If you prefer star corner points, modify the initial value field for mPoints

and rebuild the class The initial value for mLineStyle calls the cLineStyle constructor using two arguments This is an example of composition and demonstrates how easy it is to define a

/@cShape/pri-vate/ctor_ini resulting from the private variable definitions is identical to the Chapter 16

ve r s i o n T h i s fi l e a n d a l l t h e c l a s s fi l e s f o r t h i s c h a p t e r c a n b e f o u n d i n

/oop_guide/chapter_18

58 end

59 % Replace with something like UNCLASSIFIED

18.2.3 C S HAPE C ONCEALED V ARIABLES

Moving down the collection of dialog buttons brings us to the concealed variables button Click the Concealed Variables … button and enter the data shown in Figure 18.9 The concealed variable data are also provided in Table 18.5 Fields for concealed variables are the same as the fields for public variables because there is very little difference between the two In the generated functions, concealed variables are written into the concealed variable sections of get and set If you examine these files, you will notice that the mFigureHandle shares the concealed section with another concealed variable, mDisplayFunc Managed exclusively by Class Wizard, mDis-playFunc should never be included in the concealed variable dialog When you are finished, click Done to return to the main dialog

FIGURE 18.8 Class Wizard, cShape private variable dialog.

TABLE 18.4

cShape Private Variable Dialog Fields

Private Variable Name Initial Value Comment

box

values

window

([0;0;1], 1)

Secondary cLineStyle object

18.2.4 C S HAPE P UBLIC V ARIABLES

The next move down the collection of dialog buttons brings us to the public variables button Click the Public Variables … button and enter the data shown in Figure 18.10 The public variable data are also provided in Table 18.6 When you are finished, click Done to return to the main dialog All public variables defined for cShape have accessors Accessors for Size and Points

use simple, direct-link syntax, and accessors for ColorRgb and LineWeight use a helper function Internally, cShape manages color and line width through a secondary object stored in

mLineStyle Access to the color value is simple, but it does not conform to direct-link require-ments Consequently, ColorRgb must specify helper-function syntax Access to the line width is more complicated because the interface converts between strings ‘normal’ and ‘bold’ and integer width values

All public variables defined for cShape also have mutators In this case, the desire for a robust interface complete with input value checking means that all public variables use helper function syntax for mutation Helper-function stubs all look similar to the Color_helper stub in Code Listing 107 The appropriate helper-function code for cShape’s private variables was developed

in Chapter 16

FIGURE 18.9 Class Wizard, cShape concealed variable dialog.

TABLE 18.5

cShape Concealed Variable Dialog Fields

Concealed Variable

Name Type Accessor Expression

Mutator Expression Comment mFigureHandle graphics

handle

mFigureHandle The shape’s

handle-graphics handle