Wide Studio Object Reference

Wide Studio Home
Up to

## Class Name

WSClist

## Specification of methods

### setLabelHeight method

Form
  void setLabelHeight(WSCushort* height)
Function
  Specify the item height.
Description
Parameters

  (in)WSCushort height | the item height

Return value
  None.
Notice
  Call updateList() method to redraw after this.
Samples

        newlist_000->setLabelHeight(25);
        newlist_000->updateList();

  ### delAll method

  Form
    void delAll()
  Function
    Deletes all items.
  Description
  Parameters
    None.
  Return value
    None.
  Notice
    Call updateList() method to redraw after setting the item.
  Samples

          newlist_000->delAll();
          newlist_000->addItem("item1");
          newlist_000->addItem("item2");
             :
          newlist_000->updateList();

  ### getLabel method

  Form
    WSCbase* getLabel(long pos)
  Function
    Returns the internal instance that displays the item string in the list.
  Description
    You can arrange a display state of items by the instance.
  Parameters

    (in)long pos | the position of the item (Top= 0,,N-1)

  Return value
    Returns the internal instance.
  Notice
    The valid value of position is between top: 0 and bottom: N-1 (If the number of items is N). If -1 is specified, it indicates the bottom item.
  Samples

          newlist_000->addItem("item1");
          WSCbase* label = newlist_000->getLabel(-1); //get the last label..
          label->setProperty(WSNforeColor,"#ff0000"); //set the fore color red.

  ### getNum method

  Form
    void getNum()
  Function
    Returns the number of items.
  Description
  Parameters
    None.
  Return value
    None.
  Notice
    None.
  Samples

          long i;
          long num = newlist_000->getNum();
          WSCstring item;
          for(i=0; i<num; i++){
            item = newlist_000->getItem(i);
            printf("pos=%d item=%s\n",i,(char*)item);
          }

  ### getItem method

  Form
    WSCstring getItem(long pos)
  Function
    Returns the string of the specified position.
  Description
  Parameters

    (in)long pos | the position (top:0,..,N-1 or -1:bottom)

  Return value
    Returns the string as a WSCstring instance.
  Notice
    Do not receive the return value by a char* pointer because it becomes a junc pointer by internal freeing. One must receive it by the WSCstring variable.
  Samples
    Refer to getNum().

  ### addItem method

  Form
    void addItem(char* item,long pos = -1)
  Function
    Inserts the item into the specified position.
  Description
  Parameters

    (in)char* | the string
    (in)long pos | the position(top:0,..,N-1 or -1:bottom)

  Return value
    None.
  Notice
    If the specified position is -1 or none, it indicates the bottom. Please call the updateList() method to redraw after setting the item.
  Samples

          newlist_000->delAll();
          newlist_000->addItem("item0"); //add a last element.
          newlist_000->addItem("item1"); //add a last element.
          newlist_000->addItem("item2",0); //add a first element.
          newlist_000->addItem("item3",1); //add a second element.
          newlist_000->updateList();
        Results:
          item2
          item3
          item0
          item1

  ### replaceItem method

  Form
    void replaceItem(char* item,long pos)
  Function
    Replaces the item of the specified position.
  Description
    You can pass the position between top: 0 and bottom: N-1, (N: the number of items). The -1 position indicates the bottom: N-1 item.
  Parameters

    (in)char* | the string
    (in)long pos | the position (top:0,..,N-1 or -1:bottom)

  Return value
    None.
  Notice
    Please call updateList() method to redraw after replacing the item.
  Samples

          newlist_000->delAll();
          newlist_000->addItem("item1"); //add a list element.
          newlist_000->addItem("item2"); //add a list element.
          newlist_000->replaceItem("item0",-1); //replace a list element to "item0".
          newlist_000->updateList();
        Results:
          item1
          item2

  ### delPos method

  Form
    void delPos(long pos);
  Function
    Deletes the item at the specified position.
  Description
    You can specify the position between top: 0 and bottom: N-1, (N: the number of items). The -1 position indicates the bottom: N-1 item.
  Parameters

    (in)long pos | the position(top:0,..,N-1 or -1:bottom)

  Return value
    None.
  Notice
    Please call updateList() method to redraw after deleting the item.
  Samples

          newlist_000->delAll(); //clear.
          newlist_000->addItem("item0"); //add a list element.
          newlist_000->addItem("item1"); //add a list element.
          newlist_000->addItem("item2"); //add a list element.
          newlist_000->delPos(1);
          newlist_000->updateList();
        Results:
          item0
          item2

  ### getSelectedPos method

  Form
    long getSelectedPos();
  Function
    Returns the position of the selected item.
  Description
    Returns the position of the item which is selected by the mouse pointer.
  Parameters
    None.
  Return value
    Returns the position between top: 0 and bottom: N-1.
  Notice
  Samples

          long pos = newlist_000->getSelectedPos();
          printf("selected item = %d\n",pos);

  ### setSelectPos method

  Form
    void setSelectPos(long pos);
  Function
    Makes the item of the specified position selected.
  Description
    You can specify the position between top: 0 and bottom: N-1, (N: the number of items). The -1 position indicates the bottom: N-1 item.
  Parameters

    (in)long pos | the position(top:0,..,N-1 or -1:bottom)

  Return value
    None.
  Notice
  Samples

          newlist_000->delAll();
          newlist_000->addItem("item0");
          newlist_000->addItem("item1");
          newlist_000->addItem("item2");
          newlist_000->setSelectedPos(1); // make the element "item1" selected.

  ### getSelectedItem method

  Form
    char* getSelectedItem();
  Function
    Returns the string of the selected item.
  Description
  Parameters
    None.
  Return value
    Returns the string.
  Notice
    Do not delete the return value. If several items are selected, it returns the last selected one. To select all, use the getSelectedLabels() method.
  Samples

          WSCstring item;
          item = newlist_000->setSelectedItem();
          printf("selected item = %s",(char*)item);

  ### setTopPos method

  Form
    void setTopPos(long pos);
  Function
    Scrolls the list to display the item of the highest specified position.
  Description
  Parameters

    (in)long pos | the position(top: 0,..,N-1 or -1: bottom)

  Return value
    None.
  Notice
  Samples

          newlist_000->setTopPos(0); //scroll first line to the top-most.
          newlist_000->setTopPos(10); //scroll 11th line to the top-most.

  ### setBottomPos method

  Form
    void setBottomPos(long pos);
  Function
    Scrolls the list to display the item of the lowest specified position.
  Description
  Parameters

    (in)long pos | the position(top:0,..,N-1 or -1:bottom)

  Return value
    None.
  Notice

          newlist_000->setBottomPos(100); //scroll 101th line to the bottom-most.

  ### updateList method

  Form
    void updateList();
  Function
    Updates the list which is changed by the methods.
  Description
  Parameters
    None.
  Return value
    None.
  Notice
    None.
  Samples
    Refer to addItem().

  ### setLabelClass method

  Form
    void setLabelClass(char* class_name);
  Function
    Registers the class which is used to display the items.
  Function
  Description
    The items are shown by the internal instance of the specified class. The default class is WSCvlabel.
  Parameters

    (in)char* class_name | the class name

  Return value
    None.
  Notice
    Specify the class which has the property: WSNlabelString. The list class uses WSNlabelString to set the string of the items.
  Samples

          newlist_000->setLabelClass("WSCvklabel"); //specify label class name to use.

  ### getSelectItemChanged method

  Form
    WSCbool getSelectItemChanged()
  Function
    Returns the state whether the selection of the items has changed.
  Description
    If the selection of the items has changed as some items become selected afresh by clicking of the mouse, the return value is True.
  Parameters
    None.
  Return value
    Returns True if changed; returns False if not changed.
  Notice
    You need to call the method: setSlectedItemChanged(False) to clear the flag before getting a new change of the selection. Then call getSelectItemChanged() to get the change.
  Samples

          WSCbool changed = newlist_000->getSelectItemChanged();
          if (changed == False){
            //the selection is not changed.
          }else{
            //the selection is changed.
          }

  ### setSelectItemChanged method

  Form
    void setSelectItemChanged(WSCbool fl);
  Function
    Sets the value into the flag that indicates whether the selection of items has changed.
  Description
  Parameters

    (in)WSCbool fl | True / False

  Return value
    None.
  Notice
    This method is used to set the value only. Before getting the status of change by the method: getSelectItemChanged(), you need to reset the flag. If the flag is True, it stays permanently.
  Samples

          newlist_000->setSelectItemChanged(True); //set the selection state.

  ### getLabels method

  Form
    WSClistData* getLabels();
  Function
    Returns a list of internal instances which display the items.
  Description
  Parameters
  Return value
    Returns the list of instances.
  Notice
    Do not delete the return value. You can access the instances in the same way as the method: getChildren(). Cast the elements of the array [void*] into WSCbase*.
  Samples

          WSClistData* labels = newlist_000->getLabels();
          long i;
          long num = labels->getNum();
          for(i=0; i<num; i++){
            WSCbase* label = (WSCbase*)labels->getData(i);
            //directly operate the internal label instance.
          }

  ### getSelectedLabels method

  Form
    void getSelectedLabels(WSClistData& list);
  Function
    Returns the internal instances that display the selected items with the specified list.
  Description
  Parameters

    (out)WSClistData& list | the list which contains the return value

  Return value
    None.
  Notice
    You can access the instances by casting the elements of the array [void*] into WSCbase*.
  Samples

          WSClistData selected_labels;
          newlist_000->getSelectedLabels(selected_labels);
          long i;
          long num = selected_labels.getNum();
          for(i=0; i<num; i++){
            WSCbase* label = (WSCbase*)selected_labels[i];
            //directry operate the internal selected label instance.
          }

  ### setItemVisible method

  Form
    long setItemVisible(long pos,WSCbool fl);
  Function
    Sets the visiblity of the item of the specified position.
  Description
    You can specify the position between top: 0 and bottom: N-1, (N: the number of items). The -1 position indicates the bottom: N-1 item.
  Parameters

    (in)long pos | the position(top:0,..,N-1 or -1:bottom)
    (in)WSCbool fl | True: visible, False: invisible

  Return value
    Returns WS_NO_ERR if it succeeds; otherwise if it fails.
  Notice
    Use this method when you want to make an item invisible without deleting it.
  Samples

          newlist_000->setItemVisible(0,False); //make the first label invisible.

  ### setItemValue method

  Form
    long setItemValue(long pos, long kind, long bal);
  Function
    Sets the specified value into the specified attributes of the specified item.
  Description
    These are following attributes

    WS_OPEN | The open and closed status of the item on the tree mode. 0: close, 1: open
    WS_ABSOLUTE_OPEN | The open and closed status of the item on the tree mode. 0:close, 1: open
    WS_INDENT_LEVEL | The indent level of the item on the tree mode. 0: most left(parent),1,2,...

    Notice: WS_ABSOLUTE_OPEN affects all parent items which relate to the specified item. For example, if the parent and target items are closed and you specify the open status, they assume open status.
  Parameters

    (in)long pos | the position (top: 0,..,N-1 or -1: bottom)
    (in)long kind | the attribute
    (in)long val | the value

  Return value
    Returns WS_NO_ERR if it succeeds; otherwise if it fails.
  Notice
  Samples

          //Tree mode..
          newlist_000->delAll();
          newlist_000->addItem("item1");
          newlist_000->addItem("item2");
          newlist_000->addItem("item3");
          newlist_000->addItem("item4");
          newlist_000->addItem("item5");
          newlist_000->setItemValue(0,WS_INDENT_LEVEL,0);
          newlist_000->setItemValue(1,WS_INDENT_LEVEL,1);
          newlist_000->setItemValue(2,WS_INDENT_LEVEL,2);
          newlist_000->setItemValue(3,WS_INDENT_LEVEL,1);
          newlist_000->setItemValue(4,WS_INDENT_LEVEL,2);
          newlist_000->setItemValue(0,WS_OPEN,1);
          newlist_000->setItemValue(1,WS_OPEN,1);
          newlist_000->setItemValue(2,WS_OPEN,1);
          newlist_000->setItemValue(3,WS_OPEN,0);
        Result:
          ---item1
              +--item2
              |   +--item3
              +--item4
                ( +--item5 ) invisible

  ### getSortPos() method

  Form
    long getSortPos();
  Function
    Returns the number of the sort button on the detail mode.
  Description
    The number of the sort button is the left-most one: 0,1,...
  Return value
    Returns the number of the sort button.
  Notice
  Samples

          //get the ID of sort button on the title bar under verbatim mode.
          long pos = newlist_000->getSortPos();

  ### getTopPos() method

  Form
    long getTopPos();
  Function
    Returns the top-most line number. on the view port of the scroll area.
  Description
    Returns the top-most line number as 0,1,2,...
  Parameters
    None.
  Return value
    The top-most line number.
  Notice
  Samples

          //get the top-most line number on the view port of the scroll area.
          long pos = newlist_000->getTopPos();

  ### getBottomPos() method

  Form
    long getBottomPos();
  Function
    Returns the bottom-most line number. on the view port of the scroll area.
  Description
    Returns the bottom-most line number as 0,1,2,...
  Parameters
    None.
  Return value
    The bottom-most line number.
  Notice
  Samples

          //get the bottom-most item.
          long pos = newlist_000->getBottomPos();

  ### setEnableActivate() method

  Form
    void setEnableActivate(WSCbool fl);
  Function
    Set whether create the ACTIVATE event when the item is selected.
  Description
    It creates the ACTIVATE event if the specified value is True.
  Parameters

    (in)WSCbool fl | Whether to Create the ACTIVATE event.

  Return value
    None.
  Notice
  Samples

          //Creates ACTIVATE event if the item is selected.
          newlist_000->setEnableActivate(True);

  ### onSort() method

  Form
    void onSort();
  Function
    onSort() method is executed when the sort button is pressed under the verbatim mode.
  Description
    Instead of the event procedure by the WSEV_SORT trigger, the WSEV_SORT event can be handled by overloading of this method. It is possible to get the button ID with the getSortPos() method and sort the list.
  Parameters
    None.
  Return value
    None.
  Notice
  Samples

        void new_class::onSort(){
          //get the sort button ID.
          long btn = getSortPos();
          //do sort by the ID.

          //call the method of the parent class.
          old_class::onSort();
        }

  ### onItemSelected() method

  Form
    void onItemSelected();
  Function
    onItemSelected(), the method is executed when the elements are selected.
  Description
    Instead of the event procedure by the WSEV_ITEM_SELECTED trigger, the WSEV_ITEM_SELECTED event can be handled by overloading of this method.
  Parameters
    None.
  Return value
    None.
  Notice
  Samples

        void new_class::onItemSelected(){
          //get the selected pos.
          long pos = getSelectedPos();
          //do something..

          //call the method of the parent class.
          old_class::onItemSelected();
        }

  ### onInputFixed() method

  Form
    void onInputFixed(WSCstring str,long pos,long column);
  Function
    onInputFixed( ) method is executed when keyboard input string is fixed.
  Description
    Instead of the event procedure by the WSEV_INPUT_FIXED trigger, the WSEV_INPUT_FIXED event can be handled by overloading of this method.
  Parameters

    (in)WSCstring str | the input string
    (in)long pos | the input element number
    (in)long column | the column number under the verbatim mode

  Return value
    None.
  Notice
  Samples

        void new_class::onInputFixed(){
          //get the input string.
          WSCstring str;
          str = getInputString();

          //call the method of the parent class.
          old_class::onInputFixed();
        }

  ### cancelInput() method

  Form
    void cancelInput();
  Function
    Cancels the keyboard input string.
  Description
  Parameters
    None.
  Return value
    None.
  Notice
  Samples

          //Cancels the keyboard input string.
          newlist_000->cancelInput();

  ### getInputString() method

  Form
    void getInputString();
  Function
    Returns the keyboard input string.
  Description
  Parameters
    None.
  Return value
    The keyboard input string.
  Notice
  Samples
    Refer to onInputFixed().

  ### onKey() mentod

  Form
    void onKey(WSDkeyboard* keyboard,WSCbool keydown);
  Function
    onKey( ) is executed when the some key is input.
  Description
    Instead of the event procedure by the WSEV_KEY_PRESS/RELEASE trigger, the event can be handled by overloading of this method.
  Parameters

    (in)WSDkeyboard* keyboard | the keyboard instance
    (in)WSCbool keydown | True = Press, False = Release

  Return value
    None.
  Notice
  Samples

        void new_class::onKey(WSDkeyboard* keyboard,WSCbool keydown){
          if (keydown != False){   //key pressed.
            //get key.
            long key = keyboard->getKey();
            //get keyboard input string.
            WSCstring str = keyboard->getText();
          }

          //call the method of the parent class.
          old_class::onKey(keyboard,keydown);
        }

  Document Release 3.70
  For use with Wide Studio Release 3.70, Spring 2004

  Wide Studio Home | Up to

  Copyright(C) WideStudio Development Team, 1999-2004 |  | Last modified: May 25, 2004