FileDocCategorySizeDatePackage
NameRecord.javaAPI DocApache Poi 3.0.128407Mon Jan 01 12:39:40 GMT 2007org.apache.poi.hssf.record

NameRecord

public class NameRecord extends Record
Title: Name Record (aka Named Range)

Description: Defines a named range within a workbook.

REFERENCE:

author
Libin Roman (Vista Portal LDT. Developer)
author
Sergei Kozello (sergeikozello at mail.ru)
author
Glen Stampoultzis (glens at apache.org)
version
1.0-pre

Fields Summary
public static final short
sid
public static final byte
BUILTIN_CONSOLIDATE_AREA
Included for completeness sake, not implemented
public static final byte
BUILTIN_AUTO_OPEN
Included for completeness sake, not implemented
public static final byte
BUILTIN_AUTO_CLOSE
Included for completeness sake, not implemented
public static final byte
BUILTIN_DATABASE
Included for completeness sake, not implemented
public static final byte
BUILTIN_CRITERIA
Included for completeness sake, not implemented
public static final byte
BUILTIN_PRINT_AREA
public static final byte
BUILTIN_PRINT_TITLE
public static final byte
BUILTIN_RECORDER
Included for completeness sake, not implemented
public static final byte
BUILTIN_DATA_FORM
Included for completeness sake, not implemented
public static final byte
BUILTIN_AUTO_ACTIVATE
Included for completeness sake, not implemented
public static final byte
BUILTIN_AUTO_DEACTIVATE
Included for completeness sake, not implemented
public static final byte
BUILTIN_SHEET_TITLE
Included for completeness sake, not implemented
public static final short
OPT_HIDDEN_NAME
public static final short
OPT_FUNCTION_NAME
public static final short
OPT_COMMAND_NAME
public static final short
OPT_MACRO
public static final short
OPT_COMPLEX
public static final short
OPT_BUILTIN
public static final short
OPT_BINDATA
private short
field_1_option_flag
private byte
field_2_keyboard_shortcut
private byte
field_3_length_name_text
private short
field_4_length_name_definition
private short
field_5_index_to_sheet
private short
field_6_equals_to_index_to_sheet
private byte
field_7_length_custom_menu
private byte
field_8_length_description_text
private byte
field_9_length_help_topic_text
private byte
field_10_length_status_bar_text
private byte
field_11_compressed_unicode_flag
private byte
field_12_builtIn_name
private String
field_12_name_text
private Stack
field_13_name_definition
private String
field_14_custom_menu_text
private String
field_15_description_text
private String
field_16_help_topic_text
private String
field_17_status_bar_text
Constructors Summary
public NameRecord()
Creates new NameRecord



        
      
        field_13_name_definition = new Stack();

        field_12_name_text = new String();
        field_14_custom_menu_text = new String();
        field_15_description_text = new String();
        field_16_help_topic_text = new String();
        field_17_status_bar_text = new String();
public NameRecord(RecordInputStream in)
Constructs a Name record and sets its fields appropriately.

param
id id must be 0x18 or an exception will be throw upon validation
param
size the size of the data area of the record
param
data data of the record (should not contain sid/len)

        super(in);
public NameRecord(byte builtin, short index)
Constructor to create a built-in named region

param
builtin Built-in byte representation for the name record, use the public constants
param
index

	    this();	    
	    this.field_12_builtIn_name = builtin;
	    this.setOptionFlag((short)(this.getOptionFlag() | OPT_BUILTIN));
	    this.setNameTextLength((byte)1);
	    this.setEqualsToIndexToSheet(index); //the extern sheets are set through references
	    
	    //clearing these because they are not used with builtin records
		this.setCustomMenuLength((byte)0);
		this.setDescriptionTextLength((byte)0);
		this.setHelpTopicLength((byte)0);
		this.setStatusBarLength((byte)0);
Methods Summary
private org.apache.poi.hssf.record.formula.PtgcreateNewPtg()

        Ptg ptg = new Area3DPtg();
        field_13_name_definition.push(ptg);

        return ptg;
protected voidfillFields(org.apache.poi.hssf.record.RecordInputStream in)
called by the constructor, should set class level fields. Should throw runtime exception for bad/icomplete data.

param
data raw data
param
size size of data
param
offset of the record's data (provided a big array of the file)

        field_1_option_flag             = in.readShort();
        field_2_keyboard_shortcut       = in.readByte();
        field_3_length_name_text        = in.readByte();
        field_4_length_name_definition  = in.readShort();
        field_5_index_to_sheet          = in.readShort();
        field_6_equals_to_index_to_sheet= in.readShort();
        field_7_length_custom_menu      = in.readByte();
        field_8_length_description_text = in.readByte();
        field_9_length_help_topic_text  = in.readByte();
        field_10_length_status_bar_text = in.readByte();
            
			//store the name in byte form if it's a builtin name
        field_11_compressed_unicode_flag= in.readByte();        
			if (this.isBuiltInName()) {
                field_12_builtIn_name = in.readByte();
        } else {                
          if (field_11_compressed_unicode_flag == 1) {
            field_12_name_text = in.readCompressedUnicode(field_3_length_name_text);
          } else {
            field_12_name_text = in.readCompressedUnicode(field_3_length_name_text);
          }
			}
            
        field_13_name_definition = Ptg.createParsedExpressionTokens(field_4_length_name_definition, in);
    
        //Who says that this can only ever be compressed unicode???
        field_14_custom_menu_text       = in.readCompressedUnicode(LittleEndian.ubyteToInt(field_7_length_custom_menu));
    
        field_15_description_text       = in.readCompressedUnicode(LittleEndian.ubyteToInt(field_8_length_description_text));
    
        field_16_help_topic_text        = in.readCompressedUnicode(LittleEndian.ubyteToInt(field_9_length_help_topic_text));
    
        field_17_status_bar_text        = in.readCompressedUnicode(LittleEndian.ubyteToInt(field_10_length_status_bar_text));
        /*} */
public java.lang.StringgetAreaReference(org.apache.poi.hssf.model.Workbook book)
gets the reference , the area only (range)

return
area reference

        if (field_13_name_definition == null || field_13_name_definition.isEmpty()) return "Error";
        Ptg ptg = (Ptg) field_13_name_definition.peek();
        String result = "";

        if (ptg.getClass() == Area3DPtg.class){
            result = ptg.toFormulaString(book);

        } else if (ptg.getClass() == Ref3DPtg.class){
            result = ptg.toFormulaString(book);
        } else if (ptg.getClass() == DeletedArea3DPtg.class || ptg.getClass() == DeletedRef3DPtg.class) {
        	result = "#REF!"   ;     }

        return result;
public bytegetBuiltInName()
Gets the Built In Name

return
the built in Name

	    return this.field_12_builtIn_name;
public bytegetCompressedUnicodeFlag()
gets the name compressed Unicode flag

return
compressed unicode flag

        return field_11_compressed_unicode_flag;
public bytegetCustomMenuLength()
gets the custom menu length

return
custom menu length

        return field_7_length_custom_menu;
public java.lang.StringgetCustomMenuText()
get the custom menu text

return
custom menu text

        return field_14_custom_menu_text;
public shortgetDefinitionLength()
get the definition length

return
definition length

        return field_4_length_name_definition;
public java.lang.StringgetDescriptionText()
gets the description text

return
description text

        return field_15_description_text;
public bytegetDescriptionTextLength()
gets the description text length

return
description text length

        return field_8_length_description_text;
public shortgetEqualsToIndexToSheet()

        return field_6_equals_to_index_to_sheet;
public shortgetExternSheetNumber()
gets the extern sheet number

return
extern sheet index

        if (field_13_name_definition == null || field_13_name_definition.isEmpty()) return 0;
        Ptg ptg = (Ptg) field_13_name_definition.peek();
        short result = 0;

        if (ptg.getClass() == Area3DPtg.class){
            result = ((Area3DPtg) ptg).getExternSheetIndex();

        } else if (ptg.getClass() == Ref3DPtg.class){
            result = ((Ref3DPtg) ptg).getExternSheetIndex();
        }

        return result;
public bytegetFnGroup()

return
function group
see
FnGroupCountRecord

        int masked = field_1_option_flag & 0x0fc0;
        return (byte) (masked >> 4);
public bytegetHelpTopicLength()
gets the help topic length

return
help topic length

        return field_9_length_help_topic_text;
public java.lang.StringgetHelpTopicText()
get the help topic text

return
gelp topic text

        return field_16_help_topic_text;
public shortgetIndexToSheet()
Convenience method to retrieve the index the name refers to.

see
#getEqualsToIndexToSheet()
return
short

		return getEqualsToIndexToSheet();
public bytegetKeyboardShortcut()
returns the keyboard shortcut

return
keyboard shortcut

        return field_2_keyboard_shortcut ;
public java.util.ListgetNameDefinition()
gets the definition, reference (Formula)

return
definition -- can be null if we cant parse ptgs

        return field_13_name_definition;
private intgetNameDefinitionSize()

    	int result = 0;
        List list   = field_13_name_definition;
        
        for (int k = 0; k < list.size(); k++)
        {
        	Ptg ptg = ( Ptg ) list.get(k);
        	
        	result += ptg.getSize();
        }
        return result;
public java.lang.StringgetNameText()
gets the name

return
name


    	return this.isBuiltInName() ? this.translateBuiltInName(this.getBuiltInName()) : field_12_name_text;
public bytegetNameTextLength()
gets the name length

return
name length

        return field_3_length_name_text;
public shortgetOptionFlag()
gets the option flag

return
option flag

        return field_1_option_flag;
public intgetRecordSize()
returns the record size

        int result;

        result = 19 + getTextsLength() + getNameDefinitionSize();
        

        return result;
public shortgetSid()
return the non static version of the id for this record.

        return sid;
public bytegetStatusBarLength()
get the status bar text length

return
satus bar length

        return field_10_length_status_bar_text;
public java.lang.StringgetStatusBarText()
gets the status bar text

return
status bar text

        return field_17_status_bar_text;
public intgetTextsLength()
gets the length of all texts

return
total length

        int result;

        result = getNameTextLength() + getDescriptionTextLength() +
        getHelpTopicLength() + getStatusBarLength();


        return result;
public shortgetUnused()
gets the index to extern sheet

return
index to extern sheet

        return field_5_index_to_sheet;
public booleanisBuiltInName()
Convenience Function to determine if the name is a built-in name

	    return ((this.getOptionFlag() & OPT_BUILTIN) != 0);
public booleanisCommandName()

return
true if name is a command

        return (field_1_option_flag & OPT_COMMAND_NAME) != 0;
public booleanisComplexFunction()

return
true if array formula or user defined

        return (field_1_option_flag & OPT_COMPLEX) != 0;
public booleanisFunctionName()

return
true if name is a function

        return (field_1_option_flag & OPT_FUNCTION_NAME) != 0;
public booleanisHiddenName()

return
true if name is hidden

        return (field_1_option_flag & OPT_HIDDEN_NAME) != 0;
public booleanisMacro()

return
true if function macro or command macro

        return (field_1_option_flag & OPT_MACRO) != 0;
public intserialize(int offset, byte[] data)
called by the class that is responsible for writing this sucker. Subclasses should implement this so that their data is passed back in a byte array.

param
offset to begin writing at
param
data byte array containing instance data
return
number of bytes written

        LittleEndian.putShort( data, 0 + offset, sid );
        short size = (short)( 15 + getTextsLength() + getNameDefinitionSize());
        LittleEndian.putShort( data, 2 + offset, size );
        // size defined below
        LittleEndian.putShort( data, 4 + offset, getOptionFlag() );
        data[6 + offset] = getKeyboardShortcut();
        data[7 + offset] = getNameTextLength();
        LittleEndian.putShort( data, 8 + offset, getDefinitionLength() );
        LittleEndian.putShort( data, 10 + offset, getUnused() );
        LittleEndian.putShort( data, 12 + offset, getEqualsToIndexToSheet() );
        data[14 + offset] = getCustomMenuLength();
        data[15 + offset] = getDescriptionTextLength();
        data[16 + offset] = getHelpTopicLength();
        data[17 + offset] = getStatusBarLength();
        data[18 + offset] = getCompressedUnicodeFlag();

        /* temp: gjs
        if (isBuiltInName())
        {
            LittleEndian.putShort( data, 2 + offset, (short) ( 16 + field_13_raw_name_definition.length ) );

            data[19 + offset] = field_12_builtIn_name;
            System.arraycopy( field_13_raw_name_definition, 0, data, 20 + offset, field_13_raw_name_definition.length );

            return 20 + field_13_raw_name_definition.length;
        }
        else
        {     */            
            
			int start_of_name_definition = 19 + field_3_length_name_text;

			if (this.isBuiltInName()) {
				//can send the builtin name directly in
				data [19 + offset] =  this.getBuiltInName();
			} else {
				StringUtil.putCompressedUnicode( getNameText(), data, 19 + offset );
				
			}


			Ptg.serializePtgStack(field_13_name_definition,  data, start_of_name_definition + offset );


            int start_of_custom_menu_text = start_of_name_definition + field_4_length_name_definition;
            StringUtil.putCompressedUnicode( getCustomMenuText(), data, start_of_custom_menu_text + offset );

            int start_of_description_text = start_of_custom_menu_text + field_7_length_custom_menu;
            StringUtil.putCompressedUnicode( getDescriptionText(), data, start_of_description_text + offset );

            int start_of_help_topic_text = start_of_description_text + field_8_length_description_text;
            StringUtil.putCompressedUnicode( getHelpTopicText(), data, start_of_help_topic_text + offset );

            int start_of_status_bar_text = start_of_help_topic_text + field_9_length_help_topic_text;
            StringUtil.putCompressedUnicode( getStatusBarText(), data, start_of_status_bar_text + offset );

            return getRecordSize();
        /* } */
public voidsetAreaReference(java.lang.String ref)
sets the reference , the area only (range)

param
ref area reference

        //Trying to find if what ptg do we need
        RangeAddress ra = new RangeAddress(ref);
        Ptg oldPtg;
        Ptg ptg;

        if (field_13_name_definition==null ||field_13_name_definition.isEmpty()){
            field_13_name_definition = new Stack();
            oldPtg = createNewPtg();
        } else {
            //Trying to find extern sheet index
            oldPtg = (Ptg) field_13_name_definition.pop();
        }

        short externSheetIndex = 0;

        if (oldPtg.getClass() == Area3DPtg.class){
            externSheetIndex =  ((Area3DPtg) oldPtg).getExternSheetIndex();

        } else if (oldPtg.getClass() == Ref3DPtg.class){
            externSheetIndex =  ((Ref3DPtg) oldPtg).getExternSheetIndex();
        }

        if (ra.hasRange()) {
            ptg = new Area3DPtg();
            ((Area3DPtg) ptg).setExternSheetIndex(externSheetIndex);
            ((Area3DPtg) ptg).setArea(ref);
            this.setDefinitionTextLength((short)ptg.getSize());
        } else {
            ptg = new Ref3DPtg();
            ((Ref3DPtg) ptg).setExternSheetIndex(externSheetIndex);
            ((Ref3DPtg) ptg).setArea(ref);
            this.setDefinitionTextLength((short)ptg.getSize());
        }

        field_13_name_definition.push(ptg);
public voidsetCompressedUnicodeFlag(byte flag)
sets the compressed unicode flag

param
flag unicode flag

        field_11_compressed_unicode_flag = flag;
public voidsetCustomMenuLength(byte length)
sets the custom menu length

param
length custom menu length

        field_7_length_custom_menu = length;
public voidsetCustomMenuText(java.lang.String text)
sets the custom menu text

param
text custom menu text

        field_14_custom_menu_text = text;
public voidsetDefinitionTextLength(short length)
sets the definition (reference - formula) length

param
length defenition length

        field_4_length_name_definition = length;
public voidsetDescriptionText(java.lang.String text)
sets the description text

param
text the description text

        field_15_description_text = text;
public voidsetDescriptionTextLength(byte length)
sets the length of named range description

param
length description length

        field_8_length_description_text = length;
public voidsetEqualsToIndexToSheet(short value)

        field_6_equals_to_index_to_sheet = value;
public voidsetExternSheetNumber(short externSheetNumber)
sets the extern sheet number

param
externSheetNumber extern sheet number

        Ptg ptg;

        if (field_13_name_definition == null || field_13_name_definition.isEmpty()){
            field_13_name_definition = new Stack();
            ptg = createNewPtg();
        } else {
            ptg = (Ptg) field_13_name_definition.peek();
        }

        if (ptg.getClass() == Area3DPtg.class){
            ((Area3DPtg) ptg).setExternSheetIndex(externSheetNumber);

        } else if (ptg.getClass() == Ref3DPtg.class){
            ((Ref3DPtg) ptg).setExternSheetIndex(externSheetNumber);
        }
public voidsetHelpTopicLength(byte length)
sets the help topic length

param
length help topic length

        field_9_length_help_topic_text = length;
public voidsetHelpTopicText(java.lang.String text)
sets the help topic text

param
text help topix text

        field_16_help_topic_text = text;
public voidsetKeyboardShortcut(byte shortcut)
sets the keyboard shortcut

param
shortcut keyboard shortcut

        field_2_keyboard_shortcut = shortcut;
public voidsetNameDefinition(java.util.Stack nameDefinition)

        field_13_name_definition = nameDefinition;
public voidsetNameText(java.lang.String name)
sets the name of the named range

param
name named range name

        field_12_name_text = name;
public voidsetNameTextLength(byte length)
sets the name of the named range length

param
length name length

        field_3_length_name_text = length;
public voidsetOptionFlag(short flag)
sets the option flag for the named range

param
flag option flag

        field_1_option_flag = flag;
public voidsetStatusBarLength(byte length)
sets the length of the status bar text

param
length status bar text length

        field_10_length_status_bar_text = length;
public voidsetStatusBarText(java.lang.String text)
sets the status bar text

param
text status bar text

        field_17_status_bar_text = text;
public voidsetUnused(short index)
sets the index number to the extern sheet (thats is what writen in documentation but as i saw , it works differently)

param
index extern sheet index

        field_5_index_to_sheet = index;

        // field_6_equals_to_index_to_sheet is equal to field_5_index_to_sheet
//        field_6_equals_to_index_to_sheet = index;
public java.lang.StringtoString()

see
Object#toString()

        StringBuffer buffer = new StringBuffer();

        buffer.append("[NAME]\n");
        buffer.append("    .option flags         = ").append( HexDump.toHex( field_1_option_flag ) )
            .append("\n");
        buffer.append("    .keyboard shortcut    = ").append( HexDump.toHex( field_2_keyboard_shortcut ) )
            .append("\n");
        buffer.append("    .length of the name   = ").append( field_3_length_name_text )
            .append("\n");
        buffer.append("    .size of the formula data = ").append( field_4_length_name_definition )
            .append("\n");
        buffer.append("    .unused                   = ").append( field_5_index_to_sheet )
            .append("\n");
        buffer.append("    .index to sheet (1-based, 0=Global)           = ").append( field_6_equals_to_index_to_sheet )
            .append("\n");
        buffer.append("    .Length of menu text (character count)        = ").append( field_7_length_custom_menu )
            .append("\n");
        buffer.append("    .Length of description text (character count) = ").append( field_8_length_description_text )
            .append("\n");
        buffer.append("    .Length of help topic text (character count)  = ").append( field_9_length_help_topic_text )
            .append("\n");
        buffer.append("    .Length of status bar text (character count)  = ").append( field_10_length_status_bar_text )
            .append("\n");
        buffer.append("    .Name (Unicode flag)  = ").append( field_11_compressed_unicode_flag )
            .append("\n");
        buffer.append("    .Name (Unicode text)  = ").append( getNameText() )
            .append("\n");
        buffer.append("    .Menu text (Unicode string without length field)        = ").append( field_14_custom_menu_text )
            .append("\n");
        buffer.append("    .Description text (Unicode string without length field) = ").append( field_15_description_text )
            .append("\n");
        buffer.append("    .Help topic text (Unicode string without length field)  = ").append( field_16_help_topic_text )
            .append("\n");
        buffer.append("    .Status bar text (Unicode string without length field)  = ").append( field_17_status_bar_text )
            .append("\n");
        buffer.append("[/NAME]\n");
        
        return buffer.toString();
protected java.lang.StringtranslateBuiltInName(byte name)
Creates a human readable name for built in types

return
Unknown if the built-in name cannot be translated

	    switch (name)
	    {
	        case NameRecord.BUILTIN_AUTO_ACTIVATE :     return "Auto_Activate";
	        case NameRecord.BUILTIN_AUTO_CLOSE :        return "Auto_Close";
	        case NameRecord.BUILTIN_AUTO_DEACTIVATE :   return "Auto_Deactivate";
	        case NameRecord.BUILTIN_AUTO_OPEN :         return "Auto_Open";
	        case NameRecord.BUILTIN_CONSOLIDATE_AREA :  return "Consolidate_Area";
	        case NameRecord.BUILTIN_CRITERIA :          return "Criteria";
	        case NameRecord.BUILTIN_DATABASE :          return "Database";
	        case NameRecord.BUILTIN_DATA_FORM :         return "Data_Form";            
	        case NameRecord.BUILTIN_PRINT_AREA :        return "Print_Area";
	        case NameRecord.BUILTIN_PRINT_TITLE :       return "Print_Titles";
	        case NameRecord.BUILTIN_RECORDER :          return "Recorder";
	        case NameRecord.BUILTIN_SHEET_TITLE :       return "Sheet_Title";
	        
	    }
	    
	    return "Unknown";
protected voidvalidateSid(short id)
called by constructor, should throw runtime exception in the event of a record passed with a differing ID.

param
id alleged id for this record

        if (id != sid) {
            throw new RecordFormatException("NOT A valid Name RECORD");
        }