Skip to content

Commit

Permalink
Update readme, remove spurious code and fix reset function
Browse files Browse the repository at this point in the history
  • Loading branch information
colinf committed Aug 9, 2012
1 parent 95d3945 commit d324f22
Show file tree
Hide file tree
Showing 3 changed files with 64 additions and 111 deletions.
167 changes: 62 additions & 105 deletions Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@
# Listbox Menu

A Listbox Menu component with structural styling to give you a clean slate.
The Listbox Menu component is built on top of [Menu](http://github.com/component/menu).

![js listbox menu component](http://f.cl.ly/items/1Z1d3B1j283y3e200g3E/Screen%20Shot%202012-07-31%20at%203.57.10%20PM.png)
![js listbox menu component](http://colinf.github.com/listbox-menu/images/Listbox-Menu.png)

## Installation

Expand All @@ -16,10 +17,10 @@ to-do
- events for composition
- structural CSS letting you decide on style
- fluent API
- arrow key navigation

## Events

Events are inherited from Menu as listed below.
- `show` when shown
- `hide` when hidden
- `remove` (item) when an item is removed
Expand All @@ -29,128 +30,84 @@ to-do
## Example

```js
var Menu = require('menu');

var menu = new Menu;

menu
.add('Add item')
.add('Edit item', function(){ console.log('edit'); })
.add('Remove item', function(){ console.log('remove'); })
.add('Remove "Add item"', function(){
menu.remove('Add item');
menu.remove('Remove "Add item"');
});

menu.on('select', function(item){
console.log('selected "%s"', item);
});

menu.on('Add item', function(){
console.log('added an item');
var listboxMenu = require('listbox-menu');

var data = [
{
league: "Scottish Premier League",
teams: ["Aberdeen", "Celtic", "Dundee", "Dundee Utd", "Hearts", "Hibs", "Inverness CT", "Kilmarnock", "Motherwell", "Ross County", "St Johnstone", "St Mirren"]
},
{
league: "First Division",
teams: ["Airdrie", "Cowdenbeath", "Dumbarton", "Dunfermline", "Falkirk", "Hamilton", "Livingston", "Morton", "Partick Thistle", "Raith Rovers"]
},
{
league: "Second Division",
teams: ["Albion Rovers", "Alloa", "Arbroath", "Ayr Utd", "Brechin", "East Fife", "Forfar", "Queen of the South", "Stenhousemuir", "Stranraer"]
},
{
league: "Third Division",
teams: ["Annan Athletic", "Berwick Rangers", "Clyde", "East Stirlingshire", "Elgin City", "Montrose", "Peterhead", "Queens Park", "Rangers", "Stirling Albion" ]
}
];

var menu = new listboxMenu();
var submenu = new listboxMenu();
submenu.setSelectChecker(function(item) {
return confirm("Do you really want to do this?");
});

oncontextmenu = function(e){
e.preventDefault();
menu.moveTo(e.pageX, e.pageY);
menu.show();
for (var i = 0; i < data.length; i++) {
menu.add(i, data[i].league);
};
```

## API
menu.on('select', function(item){
var teams;
submenu.reset();
teams = data[parseInt(item)].teams;
for (var i = 0; i < teams.length; i++) {
submenu.add(teams[i]);
};
});

### Menu()

Create a new `Menu`:

```js
var Menu = require('menu');
var menu = new Menu();
var menu = Menu();
```

### Menu#add([slug], text, [fn])

Add a new menu item with the given `text`, optional `slug` and callback `fn`.

Using events to handle selection:

```js
menu.add('Hello');

menu.on('Hello', function(){
console.log('clicked hello');
});
```

Using callbacks:

```js
menu.add('Hello', function(){
console.log('clicked hello');
});
```

Using a custom slug, otherwise "hello" is generated
from the `text` given, which may conflict with "rich"
styling like icons within menu items, or i18n.

```js
menu.add('add-item', 'Add Item');

menu.on('add-item', function(){
console.log('clicked "Add Item"');
});

menu.add('add-item', 'Add Item', function(){
console.log('clicked "Add Item"');
submenu.on('select', function(item){
console.log('selected "%s"', item);
});
```

### Menu#remove(slug)

Remove an item by the given `slug`:

```js
menu.add('Add item');
menu.remove('Add item');
menu.moveTo(100, 100);
submenu.moveTo(275,100);
menu.show();
submenu.show();
```

Or with custom slugs:

```js
menu.add('add-item', 'Add item');
menu.remove('add-item');
```
## API

### Menu#has(slug)
As well as the Menu API, Listbox Menu adds the following.

### ListboxMenu()

Check if a menu item is present.
Create a new `ListboxMenu`:

```js
menu.add('Add item');

menu.has('Add item');
// => true

menu.has('add-item');
// => true

menu.has('Foo');
// => false
var ListboxMenu = require('listbox-menu');
var menu = new ListboxMenu();
```

### Menu#moveTo(x, y)

Move the menu to `(x, y)`.
### ListboxMenu#reset()

### Menu#show()
Empties all items from the menu.

### ListboxMenu#setSelectChecker(fn)

Show the menu.
Add a function to the Listbox Menu which will be called when a menu item is clicked. If the function returns false then the select event will be abandoned. This allows functionality such as a confirmation dialog prior to switching to a new menu item.

### Menu#hide()
## Summary of Differences from Menu

Hide the menu.
* Intended to be used as on-screen navigation menu as opposed to a contect menu
* Listbox Menu doesn't hide when clicked
* Selected item is not deselected on hover
* Allows validation of selection events (via setSelectChecker)
* Listbox menu currently doesn't support keyboard navigation

## License

Expand Down
5 changes: 2 additions & 3 deletions index.js
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,8 @@ ListboxMenu.prototype.setSelectChecker = function(checker) {
};

ListboxMenu.prototype.reset = function() {
for (var key in this.items) {
this.items[key].remove();
}
this.el.empty();
this.items = {};
}

function createSlug(str) {
Expand Down
3 changes: 0 additions & 3 deletions test/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,6 @@
menu.add(i, data[i].league);
};

menu.on('Add item', function(){
console.log('added an item');
});
menu.on('select', function(item){
var teams;
submenu.reset();
Expand Down

0 comments on commit d324f22

Please sign in to comment.