Re: st: Accessing and changing -graph- options in a program

[Gary Longton <glongton@fhcrc.org>]

Bert Jung wrote:
> I am writing a program that customizes a graph.  I want the common
> -graph- options to be available in my program, but override some of
> them with settings that I define in the program itself.  I am looking
> for a way to access and change some of the allowed -graph- options
> inside my program.
>
> In the below example, if the user does not specify the option - ,
> xtitle() - the program assigns a default value.  I can implement this
> by specifying my own option xtitle() in the syntax and then
> substituting the content of the `xtitle' macro.  But there must be a
> better way to access all those options than listing them in the
> syntax?

The easiest approach to passing user-specified graph options from your program 
to an included graph command is to use the wild card [*] option.  Any and all 
user specified options that are not otherwise explicitly included in your syntax 
command are consequently placed in the `options' macro.  This macro can then be 
included in (usually at the end of) your graph/scatter command.
Whether you additionally include specific options in your ado syntax command in 
order to test for a user override or not will depend on the type of graph option.

  (see -help repeated options- or [G] concept: repeated options)

If it is a *rightmost*, or *merged-explicit* option, then you don't need to 
worry about testing for the presence of the option in your program syntax.  By 
including the `options' macro at the end of the scatter/graph command, the first 
instance of the option, if it exists, will be ignored (or merged if there are 
otherwise unspecified suboptions included in the first instance of the option).

For example, xtitle() is merged-explicit.  Since you want a) to provide your own 
default title, and b) allow for a user overide of your default, your example 
could be more simply coded as follows:

************************
** Example for xtitle

sysuse auto, clear

cap program drop mygraph
program mygraph
    syntax varlist(min=2 max=2), [ * ]
    scatter `varlist', xtitle("default title") `options'
end

* Graph with default xtitle
mygraph  weight mpg

* Graph with user-specified xtitle
mygraph  weight mpg, xtitle("user specified xtitle")

************************

If you wish to include a program defined default for an *unique* option (eg. 
saving()) , you will probably want to explicitly include the option in you 
syntax as you did in your example, so as to include only one instance of the 
option in your -graph- call.  Unique options specified more than once in a graph 
command will return an error.


- Gary
*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/