README.org (17256B)
1 * Emojify 2 3 [[./CHANGELOG.org][file:https://img.shields.io/badge/version-v0.4-blue.svg]] [[https://melpa.org/#/emojify][file:https://melpa.org/packages/emojify-badge.svg]] [[http://stable.melpa.org/#/emojify][file:http://stable.melpa.org/packages/emojify-badge.svg]] [[https://travis-ci.org/iqbalansari/emacs-emojify][https://travis-ci.org/iqbalansari/emacs-emojify.svg?branch=master]] [[https://coveralls.io/github/iqbalansari/emacs-emojify?branch=master][https://coveralls.io/repos/github/iqbalansari/emacs-emojify/badge.svg?branch=master]] [[http://www.gnu.org/licenses/gpl-3.0.html][http://img.shields.io/:license-gpl3-blue.svg]] [[http://makeapullrequest.com][file:https://img.shields.io/badge/PRs-welcome-brightgreen.svg]] 4 5 ** Table of contents :TOC_3_gh: 6 - [[#emojify][Emojify]] 7 - [[#what-is-this][What is this?]] 8 - [[#what-does-it-look-like][What does it look like?]] 9 - [[#requirements][Requirements]] 10 - [[#installation][Installation]] 11 - [[#elpa][ELPA]] 12 - [[#usage][Usage]] 13 - [[#displaying-emojis][Displaying emojis]] 14 - [[#searching-emojis][Searching emojis]] 15 - [[#inserting-emojis][Inserting emojis]] 16 - [[#describing-emojis][Describing emojis]] 17 - [[#listing-all-emojis][Listing all emojis]] 18 - [[#customizations][Customizations]] 19 - [[#displaying-composed-text-as-emojis][Displaying composed text as emojis]] 20 - [[#displaying-emojis-in-company-mode-tooltips][Displaying emojis in company mode tooltips]] 21 - [[#configuring-the-types-of-emojis-displayed][Configuring the types of emojis displayed]] 22 - [[#configuring-how-emojis-are-displayed][Configuring how emojis are displayed]] 23 - [[#configuring-the-buffers-where-emojify-mode-is-enabled][Configuring the buffers where emojify mode is enabled]] 24 - [[#configuring-the-texts-that-are-displayed-as-emojis][Configuring the texts that are displayed as emojis]] 25 - [[#customizing-the-behaviour-when-point-enters-an-emoji][Customizing the behaviour when point enters an emoji]] 26 - [[#customizing-the-behaviour-during-isearch-mode][Customizing the behaviour during isearch-mode]] 27 - [[#customizing-the-behaviour-when-mouse-hovers-over-an-emoji][Customizing the behaviour when mouse hovers over an emoji]] 28 - [[#custom-emojis][Custom emojis]] 29 - [[#known-issues][Known issues]] 30 - [[#contributing][Contributing]] 31 - [[#thanks][Thanks]] 32 - [[#credits][Credits]] 33 - [[#licence][Licence]] 34 - [[#emojione-images][EmojiOne images]] 35 - [[#twemoji-images][Twemoji images]] 36 - [[#source-code][Source code]] 37 38 ** What is this? 39 Emojify is an Emacs extension to display emojis. It can display github style 40 emojis like ~:smile:~ or plain ascii ones like ~:)~. It tries to be as 41 efficient as possible, while also providing a lot of [[#customizations][flexibility]] 42 43 ** What does it look like? 44 Here is how the commit log of this project looks with emojify mode enabled 45 46 [[https://raw.githubusercontent.com/iqbalansari/emacs-emojify/master/screenshots/emojify-in-action.png][screenshots/emojify-in-action.png?raw=true]] 47 48 If you prefer a GIF you can view one [[https://raw.githubusercontent.com/iqbalansari/emacs-emojify/master/screenshots/emojify-in-action.gif][here]]. 49 50 ** Requirements 51 This package requires Emacs *v24.3* and above. Emacs should be compiled with 52 support for *PNG* images to display emojis as images. It is *recommended* 53 that Emacs is compiled with *ImageMagick* support. ~emojify~ will use it to 54 resize emojis if needed, additionally imagemagick is used to set background 55 color for emojis to workaround the bug described in [[https://github.com/iqbalansari/emacs-emojify/issues/7][issue 7]]. However these 56 are *completely optional*. 57 58 PNG support might require some additional steps to on Windows, you might find 59 [[http://stackoverflow.com/questions/2650041/emacs-under-windows-and-png-files][this]] stackoverflow answer helpful. 60 61 ** Installation 62 *** ELPA 63 ~emojify~ is available on [[http://melpa.org/#/emojify][MELPA]] and [[http://stable.melpa.org/#/emojify][MELPA Stable]]. Please follow the instructions on MELPA 64 [[http://melpa.org/#/getting-started][website]] to enable it, if you haven't already. 65 66 You can then install ~emojify~ from the [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Menu.html][package menu]]. Alternatively install it by doing the following 67 68 Refresh the package index 69 #+BEGIN_QUOTE 70 M-x package-refresh-contents RET 71 #+END_QUOTE 72 73 And then install it by doing 74 #+BEGIN_QUOTE 75 M-x package-install RET emojify 76 #+END_QUOTE 77 **** With use-package 78 #+begin_src elisp 79 (use-package emojify 80 :hook (after-init . global-emojify-mode)) 81 #+end_src 82 ** Usage 83 *** Displaying emojis 84 ~emojify-mode~ can be enabled/disabled separately for a buffer by using the 85 command ~emojify-mode~, to enable/disable it globally use the command 86 ~global-emojify-mode~. 87 88 To enable ~emojify-mode~ globally at startup add something like the 89 following to your ~init~ file 90 91 #+BEGIN_SRC emacs-lisp 92 (add-hook 'after-init-hook #'global-emojify-mode) 93 #+END_SRC 94 95 Emojify integrates with packages like ~prettify-symbol-mode~ and 96 ~org-bullets-mode~ which display text differently, if the alternate text 97 displayed by these packages match an emoji, ~emojify~ will display them too. 98 See [[#displaying-composed-text-as-emojis][Displaying composed text as emojis]] for more details. Emojify can also 99 display emojis in ~company-mode~ tooltips, see [[#displaying-emojis-in-company-mode-tooltips][Displaying emojis in company mode tooltips]] 100 for more details. 101 102 *[EXPERIMENTAL]* Emojify can be used for displaying emojis in the mode-line, 103 to enable/disable it for individual buffers use the command 104 ~emojify-mode-line-mode~, to enable/disable it globally use the command 105 ~global-emojify-mode-line-mode~. 106 107 *** Searching emojis 108 The command ~emojify-apropos-emoji~ can be used to display emojis that match 109 given regexp/apropos pattern. The results are displayed in a specialized 110 buffer, where ~w~ or ~c~ can be used to copy emojis to the kill ring. 111 112 *** Inserting emojis 113 The command ~emojify-insert-emoji~ can be used to insert emojis 114 interactively. While the command works with vanilla Emacs completion system, 115 the experience would be better with something like [[https://github.com/emacs-helm/helm][Helm]], [[https://github.com/abo-abo/swiper][Ivy]], [[https://www.emacswiki.org/emacs/Icicles][Icicles]] or Ido 116 depending on you preference. 117 118 *** Describing emojis 119 The command ~emojify-describe-emoji-at-point~ can be used to view 120 explanation about the command displayed at point. Additionally the command 121 ~emojify-describe-emoji~ can be used to display description for an arbitrary 122 emoji. 123 124 *** Listing all emojis 125 The command ~emojify-list-emojis~ can be used to view all the available emojis 126 in a list form. 127 128 ** Customizations 129 *** Displaying composed text as emojis 130 Emacs provides a way to modify how some parts of buffer are displayed using 131 the ~composition~ text property. ~prettify-symbol-mode~ and 132 ~org-bullets-mode~ are some popular packages that use this feature to 133 display certain text in the buffer differently. 134 135 If the alternate display matches an emoji then ~emojify~ will display those 136 as emojis too. This is default behaviour. You can disable this behaviour by 137 setting ~emojify-composed-text-p~ to ~nil~. 138 139 *** Displaying emojis in company mode tooltips 140 Emojify can also display emojis that are part of company-mode's completion 141 tooltip (see [[https://github.com/dunn/company-emoji][company-emoji]] for an example of such tooltips). However this 142 feature is turned off by default. To turn it on set 143 ~emojify-company-tooltips-p~ to ~t~. 144 145 *** Configuring the types of emojis displayed 146 Emojify by default displays plain text emojis (~:)~), unicode emojis (~😄~) 147 and github style emojis ~:smile:~. However this is customizable. You can do 148 so by changing the value of ~emojify-emoji-styles~ using the customize 149 interface. To change the value of the variable from Lisp using the function 150 ~emojify-set-emoji-styles~ (or set it before loading ~emojify~), call it with 151 one parameter the list of styles that you want to be displayed. The possible 152 styles are 153 154 - ascii - Display only plain ascii emojis 155 - unicode - Display only unicode emojis 156 - github - Display only github style emojis 157 158 *** Configuring how emojis are displayed 159 By default emojis are displayed using images. However you can instruct emojify 160 to display it using unicode characters or ascii characters. To do so customize 161 the variable ~emojify-display-style~. 162 163 You can set it one of the following values 164 - image - Display emojis using images, obviously this requires the Emacs 165 instance to support image 166 - unicode - Display emojis using unicode characters, this might be a good 167 option on platforms with good emoji fonts 168 - ascii - This is simplest and does not require any external dependencies 169 In this case emojify will display ascii equivalents of github 170 style emojis. 171 172 *** Configuring the buffers where emojify mode is enabled 173 You can control the buffers where emojify is enabled using 174 ~emojify-inhibit-major-modes~ and ~emojify-inhibit-in-buffer-functions~. 175 176 **** Major modes where emojify-mode should be not be enabled 177 As the names suggests ~emojify-inhibit-major-modes~ is a list of major-modes 178 where ~emojify~ should not be enabled. 179 180 **** Inhibiting emojify-mode using custom functions 181 ~emojify-inhibit-in-buffer-functions~ is a list of functions that ~emojify~ 182 calls before enabling ~emojify-mode~ in a buffer. If any of the functions 183 return a non-nil value ~emojify-mode~ is not enabled in the buffer. Users 184 can add custom functions to this list if they wish to inhibit ~emojify~ in 185 certain buffers. The functions are called with one argument the buffer 186 where ~emojify-mode~ is about to be enabled. 187 188 *** Configuring the texts that are displayed as emojis 189 ~emojify~ offers two variables to inhibit the display of certain emojis. 190 191 **** Controlling the display of emojis in programming modes 192 If enabled in programming modes ~emojify~ by default will display only emojis 193 in string and comments. This behaviour can be customized using the variable 194 ~emojify-prog-contexts~. The variable can be set to one of the following values 195 196 - comments - Display emojis only in comments 197 - string - Display emojis only in string 198 - both - Display emojis in comments as well as string 199 - none - Do not display emojis in programming modes 200 201 **** Inhibiting display of emojis using custom functions 202 ~emojify-inhibit-functions~ is a list of function ~emojify~ calls before 203 displaying certain text as emoji, if any of the functions return a non-nil 204 value the corresponding text is not displayed as emoji. Users can add 205 custom functions to this list, if they inhibit display of emojis in under 206 certain conditions. The functions are called with three arguments 207 208 - text - The text that is about to be displayed as an emoji 209 - beg - The beginning point of text in the buffer 210 - end - The ending point of text in the buffer 211 212 These functions are called with the buffer where emoji is being displayed 213 selected. 214 215 *** Customizing the behaviour when point enters an emoji 216 The behaviour when point enters an emoji can be customized using the 217 variable ~emojify-point-entered-behaviour~. It can have one of the following 218 values 219 220 - echo - Display the emojified text in the minibuffer 221 - uncover - Temporarily display the underlying text while point is in the emojified text 222 223 Additionally it can be set to a custom function, the function is called with 224 two parameters (the buffer where the emoji appears is selected while running 225 the function) 226 227 - beg - The beginning position of the text displayed as emoji 228 - end - The ending position of the text displayed as emoji 229 230 The return value of the function is ignored. 231 232 *Note:* The custom function will be called for once for each character in an 233 emoji as point moves through them. Avoid manipulating the buffer in these 234 functions 235 236 *** Customizing the behaviour during isearch-mode 237 By default in isearch-mode the underlying emoji is displayed temporarily 238 when point enters the emoji while searching (similar to ~uncover~ behaviour 239 mentioned [[#controlling-behaviour-when-point-enters-an-emoji][above]]). This can be disabled by setting 240 ~emojify-reveal-on-isearch~ to ~nil~. 241 242 *** Customizing the behaviour when mouse hovers over an emoji 243 When mouse hovers over a emoji, the underlying text is displayed in a help 244 popup. This behaviour can be disabled by setting ~emojify-show-help~ to nil. 245 246 *** Custom emojis 247 You can specify custom emojis using the ~emojify-user-emojis~ variable. You 248 need to set it to an alist where first element of cons is the text to be 249 displayed as emoji, while the second element of the cons is an alist 250 containing data about the emoji. 251 252 The inner alist should have atleast 253 254 1) "name" - The name of the emoji 255 2) "style" - This should be one of "github", "ascii" or "github" 256 257 Additionally the alist should contain one of (see [[#configuring-the-types-of-emojis-displayed][emojify-display-style]]) 258 1) "unicode" - The replacement for the provided emoji for "unicode" display style 259 2) "image" - The replacement for the provided emoji for "image" display style. 260 This should be the *absolute* path to the image 261 3) "ascii" - The replacement for the provided emoji for "ascii" display style 262 263 It is best to set this variable before you load ~emojify~, in case you set 264 this variable after loading ~emojify~ run the function 265 ~emojify-set-emoji-data~ to recalculate emoji data. 266 267 User emojis take precedence over default emojis so the above mechanism can 268 also be used to override the default emojis 269 270 **** Example 271 Below is an example of setting up custom emojis. Assuming that the custom 272 images are at ~\~/.emacs.d/emojis/trollface.png~ and 273 ~\~/.emacs.d/emojis/neckbeard.png~, you instruct ~emojify~ to display ~:trollface:~ 274 and ~:neckbeard:~ as :trollface: and :neckbeard: 275 276 #+BEGIN_SRC emacs-lisp 277 (setq emojify-user-emojis '((":trollface:" . (("name" . "Troll Face") 278 ("image" . "~/.emacs.d/emojis/trollface.png") 279 ("style" . "github"))) 280 (":neckbeard:" . (("name" . "Neckbeard") 281 ("image" . "~/.emacs.d/emojis/neckbeard.png") 282 ("style" . "github"))))) 283 284 ;; If emojify is already loaded refresh emoji data 285 (when (featurep 'emojify) 286 (emojify-set-emoji-data)) 287 #+END_SRC 288 289 ** Known issues 290 - Emojis are not properly updated after customizing ~emojify-display-style~ or 291 ~emojify-program-contexts~. For time being you will be fine as long as you 292 set these variables before ~emojify~ has loaded. 293 - Some of the emojis prompted in the commands like ~emojify-insert-emoji~ might 294 not be displayed by ~emojify~, this might happen if you have newer emoji 295 data but old set of images. Download the latest emoji image using ~emojify-download-emoji~ 296 and set ~emojify-emoji-set~ to the downloaded set. 297 298 ** Contributing 299 Code as well as documentation contributions are welcome. 300 301 [[https://github.com/cask/cask][Cask]] is used to manage project dependencies so make sure you have it 302 installed. To run the tests you need to install the dependencies by running 303 the following 304 305 #+BEGIN_SRC sh 306 cask install 307 #+END_SRC 308 309 After the installation completes you can run the tests by running the 310 following command 311 312 #+BEGIN_SRC sh 313 cask exec ert-runner 314 #+END_SRC 315 316 ** Thanks 317 Special thanks to @ryanprior for bug reports and valuable feedback on the 318 issue tracker. 319 320 ** Credits 321 Emoji set designed and offered free by [[http://emojione.com][Emoji One]]. 322 323 ** Licence 324 *** EmojiOne images 325 The emoji images are distributed under [[http://creativecommons.org/licenses/by-sa/4.0/][Creative Commons License]] (CC-BY-SA). 326 327 *** OpenMoji images 328 All emojis designed by [[https://openmoji.org/][OpenMoji]] – the open-source emoji and icon project. License: [[https://creativecommons.org/licenses/by-sa/4.0/#][CC BY-SA 4.0]] 329 330 *** Twemoji images 331 Copyright 2018 Twitter, Inc and other contributors 332 Code licensed under the MIT License: http://opensource.org/licenses/MIT 333 Graphics licensed under CC-BY 4.0: https://creativecommons.org/licenses/by/4.0/ 334 335 *** Source code 336 The source code is distributed under [[http://www.gnu.org/licenses/quick-guide-gplv3.html][GNU General Public License v3]]. See [[LICENSE][LICENSE]].