Skip to content

Commit

Permalink
v1.1.0
Browse files Browse the repository at this point in the history
version 1.1.0 release
  • Loading branch information
ChapelR committed Oct 14, 2018
1 parent e4ec7b9 commit 658b001
Show file tree
Hide file tree
Showing 13 changed files with 307 additions and 40 deletions.
2 changes: 1 addition & 1 deletion dist/harlowe-audio.min.css

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions dist/harlowe-audio.min.js

Large diffs are not rendered by default.

138 changes: 136 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,10 +59,15 @@ var options = {
storagekey : '%%tw-audio',
persistPrefs : true,
globalA : true,
includeFixes : true,
includeFixes : false,
controls : {
show : true,
startClosed : true
startClosed : true,
volumeDisplay : true
},
loadLimit : {
track : 500,
total : 8000
}
};
```
Expand Down Expand Up @@ -149,6 +154,30 @@ The control panel slides in and out from the side of the screen. Use this option

---

- **the `controls.volumeDisplay` option**

Set this option to `true` or `false`.

Determines whether a text readout of the current volume is displayed next to the volume control.

---

- **the `loadLimit.track` option**

Set this option to number of milliseconds.

Use this option to set a tolerance (in MS) for how long the preloading function will wait attempting to load a single track before moving on. In combination with the below option, this setting should be used to make sure the game doesn't just hang forever on slower connections.

---

- **the `loadLimit.total` option**

Set this option to number of milliseconds.

Use this option to set a tolerance (in MS) for how long the preloading function will wait attempting to load all of the tracks before dismissing the load screen. In combination with the above option, this setting should be used to make sure the game doesn't just hang forever on slower connections.

---

## Tracks

Tracks are the meat and potatoes of this library: everything you do is with tracks. Setting up your tracks should be done early, and you have a few options: use [a `startup`-tagged passage](https://twine2.neocities.org/#passagetag_startup) and `<script>` elements, or write the track definitions in JavaScript (but after the library).
Expand Down Expand Up @@ -725,6 +754,111 @@ Makes the panel visible after hiding it.

This library adds a loading screen to Harlowe that is superficially similar to SugarCube's. You can use this load screen by calling the `A.preload()` method after defining some tracks. You can potentially use it for other things too, if you want. Show it by calling `A.loadScreen.show()`, and get rid of it with `A.loadScreen.dismiss()`. That's really all there is to it.

## The Menu API

> TODO: Add this to the API section. Improve this aspect of the demo. Write code examples.
This API allows you to add links to the sidebar as a 'story menu', similar to what can be done in SugarCube. THese links can be used to navigate to a passage, run a JavaScript function, or both. They can be hidden, shown, toggled, and removed at any time.

---

- **the `A.menu.hide()` method**

- Arguments: none.

- Returns: the `#story-menu` element (jQuery).

Hides the story menu portion of the side bar.

---

- **the `A.menu.show()` method**

- Arguments: none.

- Returns: the `#story-menu` element (jQuery).

Shows the story menu portion of the side bar.

---

- **the `A.menu.isShown()` method**

- Arguments: none.

- Returns: boolean.

Returns whether the story menu portion of the side bar is currently visible.

---

- **the `A.menu.links.add(linkText, [passageName], [callback])` method**

- Arguments:
- `linkText`: (string) the text of the link.
- `passageName`: (optional) (string) a passage name to navigate to when the link is clicked.
- `callback`: (optional) (string) a function to run when the link is clicked.

- Returns: the generated link (jQuery).

This method creates a story menu link. You must pass it text to display or it will raise an error. You can then pass it a passage name to navigate to, a callback function to run on click, both, or neither. If you include both, they must be included in the indicated order.

---

- **the `A.menu.links.clear()` method**

- Arguments: none.

- Returns: the `#story-menu` element (jQuery).

This method removes all of the links from the story menu.

---

- **the `A.menu.links.hide(text)` method**

- Arguments:
-`text`: the text of the link you want to alter.

- Returns: nothing.

This method hides a story menu link. If there are multiple links with the same link text, all of them will be hidden.

---

- **the `A.menu.links.show(text)` method**

- Arguments:
-`text`: the text of the link you want to alter.

- Returns: nothing.

This method shows a hidden story menu link. If there are multiple links with the same link text, all of them will be shown.

---

- **the `A.menu.links.toggle(text)` method**

- Arguments:
-`text`: the text of the link you want to alter.

- Returns: nothing.

This method toggles the visibility a story menu link (hiding it if it's visible, showing it if it is hidden). If there are multiple links with the same link text, all of them will be toggled.

---

- **the `A.menu.links.remove(text)` method**

- Arguments:
-`text`: the text of the link you want to alter.

- Returns: nothing.

This method removes a story menu link. If there are multiple links with the same link text, all of them will be removed. Hidden links can be re-shown later, removed links are gone for good and will need to be recreated via `A.menu.links.add()`.

---

# Detailed Examples

Some more detailed examples and explanations of common use-cases.
Expand Down
2 changes: 1 addition & 1 deletion docs/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This version marks the first non-beta release version! Don't fear using this in

- Fixed preloading bugs on mobile.
- Cleaned up sidebar controls UI.
- Created API for accessing and editing the UI from user code.
- Created API for accessing and editing the UI from user code; see the docs for the `A.menu` APIs.
- Fixed mobile UI scaling in the demo, but unfortunately it can't be fixed from within the library.
- Internal improvements.

Expand Down
27 changes: 21 additions & 6 deletions docs/demo/index.html

Large diffs are not rendered by default.

21 changes: 20 additions & 1 deletion docs/demo/twee/start.twee
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,20 @@
A.preload();
</script>

:: story-menu [startup]
<script>
A.menu.links.add('Navigate', 'other passage');
A.menu.links.add('Alert', function () {
alert('This is an alert.');
});
A.menu.links.add('Both', 'other passage', function () {
alert('This is an alert.');
});
A.menu.links.add('Removes self.', function () {
A.menu.links.remove('Removes self.');
});
</script>

:: Start
<script>A.playlist('bgm').random().loop(true).playWhenPossible();</script>\
Welcome to the Harlowe Audio Library demo!
Expand Down Expand Up @@ -78,4 +92,9 @@ Tests:
A.group('bgm').mute(false);
</script>
]
}
}

:: other passage
This is another passage!

[[Go back.|Start]]
4 changes: 4 additions & 0 deletions src/controlpanel.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@
.attr('id', 'vol-title')
.append('Volume');

if (!options.controls.volumeDisplay) {
$volTitle.css('display', 'none');
}

var $volume = $(document.createElement('input'))
.attr({
id : 'audio-volume',
Expand Down
9 changes: 8 additions & 1 deletion src/panel.css
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,18 @@ div#story-menu {
tw-link.story-menu {
width: 100%;
display: block;
background: #eee;
font-weight: normal;
background: #ccc;
font-size: 0.9em;
padding: 0.1em 0;
color: #111;
border: 1px solid #333;
}

tw-link.story-menu.hide {
display: none;
}

tw-link.story-menu:hover {
opacity: 0.8;
}
Expand Down
87 changes: 70 additions & 17 deletions src/userland.js
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
(function () {
'use strict';

// userland sidebar editing

var _engine = Engine;

// userland sidebar editing
var $user = Chapel.Audio.controls.$user;

function checkDisp () {
Expand All @@ -15,46 +16,98 @@
if (!checkDisp()) {
$user.css('display', 'block');
}
return $user;
}

function hideUserMenu () {
if (checkDisp()) {
$user.css('display', 'none');
}
return $user;
}

function addLinks (text, psg, cb) {
// add tw-link elements to the userland sidebar area
if (!cb && typeof psg === 'function') {
cb = psg;
psg = null;
}
if (!psg || typeof psg !== 'string') {
psg = null;
}
if (!cb || typeof cb !== 'function') {
cb = null;
}
var passage, callback;

if (!text || typeof text !== 'string') {
var msg = 'Cannot add a link with the text "' + (text === undefined) ? 'undefined' : JSON.stringify(text) + '".';
alert(msg);
console.error(msg);
return;
}

if (!cb && typeof psg === 'function') {
callback = psg;
passage = null;
} else {
if (psg && typeof psg === 'string') {
passage = psg;
}
if (cb && typeof cb === 'function') {
callback = cb;
}
}

var $link = $(document.createElement('tw-link'))
.append(text)
.attr('tabindex', '0')
.attr({
tabindex : '0',
name : text.toLowerCase().trim()
})
.on('click', function () {
if (psg) {
_engine.goToPassage(psg);
if (passage) {
_engine.goToPassage(passage);
}
if (cb) {
cb();
if (callback) {
callback();
}
})
.addClass('story-menu')
.appendTo($user);

showUserMenu();

return $link;
}

function clearLinks () {
$user.empty();
return hideUserMenu();
}

function hideLink (text) {
text = text.toLowerCase().trim();
$('tw-link.story-menu[name="' + text + '"]').addClass('hide');
}

function showLink (text) {
text = text.toLowerCase().trim();
$('tw-link.story-menu[name="' + text + '"]').removeClass('hide');
}

function toggleLink (text) {
text = text.toLowerCase().trim();
$('tw-link.story-menu[name="' + text + '"]').toggleClass('hide');
}

Chapel.Audio.sidebar = { add : addLinks };
function deleteLink (text) {
text = text.toLowerCase().trim();
$('tw-link.story-menu[name="' + text + '"]').remove();
}

Chapel.Audio.menu = {
hide : hideUserMenu,
show : showUserMenu,
isShown : checkDisp,
links : {
add : addLinks,
clear : clearLinks,
hide : hideLink,
show : showLink,
toggle : toggleLink,
remove : deleteLink
}
};

}());
2 changes: 1 addition & 1 deletion src/wrap/min.js

Large diffs are not rendered by default.

3 changes: 2 additions & 1 deletion src/wrap/wrapper.js
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@
includeFixes : false,
controls : {
show : true,
startClosed : true
startClosed : true,
volumeDisplay : true
},
loadLimit : {
track : 500,
Expand Down
Loading

0 comments on commit 658b001

Please sign in to comment.